@file-viewer/geometry-engine 2.1.29 → 2.2.0

package/README.en.md

@@ -1,24 +1,44 @@
 # @file-viewer/geometry-engine
 
-Framework-neutral geometry-kernel boundary package for Flyfish File Viewer. It does not bundle heavy OpenCascade, web-ifc, or rhino3dm WASM runtimes by default. It currently provides STEP, IGES, IFC, 3DM, and BREP detection, signature inspection, recommended engine routes, and user-facing notices.
+Framework-neutral, UI-free geometry kernel for Flyfish File Viewer. It now decodes STEP / STP, IGES / IGS, and BREP directly in the browser: OCCT tessellation runs in a local worker, with no upload or server-side conversion. IFC and Rhino 3DM currently provide signature detection and accurate capability notices only; their full geometry renderers are not wired yet.
 
 ```ts
-import {
-  inspectGeometryKernelFile,
-  formatGeometryKernelNotice,
-} from '@file-viewer/geometry-engine'
+import { importOcctGeometryFile } from '@file-viewer/geometry-engine'
 
-const inspection = inspectGeometryKernelFile(new Uint8Array(buffer), 'step')
-const notice = formatGeometryKernelNotice(inspection.format, 'en-US')
+const result = await importOcctGeometryFile(buffer, 'step', {
+  workerUrl: '/viewer-assets/wasm/model/occt-worker.js',
+  runtimeUrl: '/viewer-assets/wasm/model/occt-import-js.js',
+  wasmUrl: '/viewer-assets/wasm/model/occt-import-js.wasm',
+  params: {
+    linearUnit: 'millimeter',
+    linearDeflectionType: 'bounding_box_ratio',
+    linearDeflection: 0.001,
+    angularDeflection: 0.5,
+  },
+})
 ```
 
-## Scope
+`result` contains the OCCT assembly hierarchy, meshes, normals, indices, and face colors for conversion into Three.js or another rendering layer. Parsing uses a one-shot worker by default and transfers both source bytes and mesh buffers. The worker is released after success, cancellation, failure, or timeout. `timeoutMs` defaults to 120 seconds. Set `useWorker: false` only when workers are genuinely unavailable, because that fallback parses on the main thread.
 
-- `inspectGeometryKernelFile()` reads a small file prefix and detects common STEP / IGES / IFC / 3DM / BREP signatures.
-- `geometryKernelRoutes` documents the recommended WASM path: OpenCascade / OCCT for STEP, IGES, and BREP; `web-ifc` / That Open for IFC; McNeel `rhino3dm` for Rhino 3DM.
-- `@file-viewer/renderer-3d` consumes this package for accurate conversion guidance without pulling CAD/BIM kernels into core or the default 3D install path.
-- Full visual rendering can evolve here later, or split into focused packages such as `@file-viewer/geometry-occt`, `@file-viewer/geometry-ifc`, and `@file-viewer/geometry-3dm`.
+## Offline Assets
 
-## Why This Package Exists
+The runtime never falls back to a CDN. Deploy these files with the viewer:
 
-STEP, IGES, IFC, and 3DM are not lightweight formats that ordinary Three.js loaders can faithfully decode. They need CAD/BIM kernels, worker isolation, WASM asset hosting, license review, and real-world sample regression. Keeping the boundary in a separate package lets `@file-viewer/core` stay fast to install while engineering-format fidelity can evolve independently, the same way the native PPTX engine does.
+- `wasm/model/occt-worker.js`
+- `wasm/model/occt-import-js.js`
+- `wasm/model/occt-import-js.wasm`
+- `wasm/model/LICENSE.occt.txt`
+- `wasm/model/LICENSE.occt-import-js.txt`
+
+`@file-viewer/vite-plugin`, full packages, and the repository build scripts copy these assets. A bare package integration must self-host them and provide `workerUrl`, `runtimeUrl`, and `wasmUrl`. For subpath deployments, asset domains, or controlled gateways, pass final absolute URLs or correctly prefixed URLs instead of relying on the site root.
+
+A strict CSP must at least allow the asset origin in `worker-src`, `script-src`, and `connect-src` for the WASM fetch; some browsers also require `script-src 'wasm-unsafe-eval'` to compile WebAssembly. The classic worker loads the local runtime with `importScripts()`, so allowing only the WASM file is not sufficient.
+
+## Boundaries
+
+- `inspectGeometryKernelFile()` still offers prefix-only detection for common STEP / IGES / IFC / 3DM / BREP signatures.
+- STEP / STP, IGES / IGS, and BREP use `occt-import-js` / OpenCascade and have a complete mesh-preview path.
+- IFC still needs a dedicated `web-ifc` / That Open integration; 3DM still needs McNeel `rhino3dm`. Neither format is presented as fully previewable yet.
+- The OCCT and `occt-import-js` license notices must ship with the offline assets.
+
+Keeping this heavy path in a separate package lets `@file-viewer/core` stay small while worker, WASM, licensing, and real engineering-file regressions remain independently maintainable.

package/README.md

@@ -1,24 +1,44 @@
 # @file-viewer/geometry-engine
 
-Flyfish File Viewer 的独立几何内核边界包。它不包含 UI，也不默认打包 OpenCascade、web-ifc 或 rhino3dm 这类重型 WASM 运行时；当前负责 STEP、IGES、IFC、3DM 和 BREP 的格式识别、文件头检查、推荐内核路线和对外提示文本。
+Flyfish File Viewer 的无 UI、框架无关几何内核包。它已经提供浏览器原生的 STEP / STP、IGES / IGS 和 BREP 解析：文件在本地 OCCT Worker 中完成三角化，不需要上传或服务端转换。IFC 和 Rhino 3DM 目前只提供格式识别与准确的能力提示，尚未接入完整几何渲染。
 
 ```ts
-import {
-  inspectGeometryKernelFile,
-  formatGeometryKernelNotice,
-} from '@file-viewer/geometry-engine'
+import { importOcctGeometryFile } from '@file-viewer/geometry-engine'
 
-const inspection = inspectGeometryKernelFile(new Uint8Array(buffer), 'step')
-const notice = formatGeometryKernelNotice(inspection.format)
+const result = await importOcctGeometryFile(buffer, 'step', {
+  workerUrl: '/viewer-assets/wasm/model/occt-worker.js',
+  runtimeUrl: '/viewer-assets/wasm/model/occt-import-js.js',
+  wasmUrl: '/viewer-assets/wasm/model/occt-import-js.wasm',
+  params: {
+    linearUnit: 'millimeter',
+    linearDeflectionType: 'bounding_box_ratio',
+    linearDeflection: 0.001,
+    angularDeflection: 0.5,
+  },
+})
 ```
 
-## 定位
+`result` 包含 OCCT 输出的装配层级、网格、法线、索引和面颜色信息，可继续转换为 Three.js 或其他渲染对象。解析默认在一次性 Worker 中执行，文件字节和网格缓冲区使用 transferable 传递；完成、取消、报错或超时后 Worker 都会释放。`timeoutMs` 默认是 120 秒。只有 Worker 确实不可用时才建议设置 `useWorker: false`，因为回退会占用主线程。
 
-- `inspectGeometryKernelFile()` 读取文件前缀，识别 STEP / IGES / IFC / 3DM / BREP 的常见签名。
-- `geometryKernelRoutes` 明确每个格式的推荐 WASM 路线：STEP / IGES / BREP 走 OpenCascade / OCCT，IFC 走 `web-ifc` / That Open，3DM 走 McNeel `rhino3dm`。
-- `@file-viewer/renderer-3d` 使用本包展示专业、准确的转换说明；core 和普通 3D 预览不会因此安装 CAD/BIM 几何内核。
-- 后续完整可视渲染可以继续在这个包中分层演进，或拆出更细的 `@file-viewer/geometry-occt`、`@file-viewer/geometry-ifc`、`@file-viewer/geometry-3dm`。
+## 离线资产
 
-## 为什么单独拆包
+运行时不访问 CDN。部署时需要把下列文件放到同一套静态资源中：
 
-STEP、IGES、IFC 和 3DM 都不是普通 Three.js loader 可以完整还原的轻量格式。它们需要 CAD/BIM 专业内核、Worker 隔离、WASM 资产托管、许可证边界和真实样本长期回归。把这条路线单独固定下来，可以让 `@file-viewer/core` 保持快速安装，让工程格式能力像 PPTX 一样独立维护、独立发布。
+- `wasm/model/occt-worker.js`
+- `wasm/model/occt-import-js.js`
+- `wasm/model/occt-import-js.wasm`
+- `wasm/model/LICENSE.occt.txt`
+- `wasm/model/LICENSE.occt-import-js.txt`
+
+`@file-viewer/vite-plugin`、full 包和仓库构建脚本会复制这些资产。直接集成本包时，需要自行托管并传入 `workerUrl`、`runtimeUrl` 和 `wasmUrl`。应用部署在子路径、资源域名或受控网关下时，请传入最终可访问的绝对 URL 或带前缀 URL，不要依赖站点根路径。
+
+严格 CSP 至少应允许资产来源出现在 `worker-src`、`script-src` 和用于获取 WASM 的 `connect-src` 中；部分浏览器还要求 `script-src 'wasm-unsafe-eval'` 才能编译 WebAssembly。Worker 使用本地 `importScripts()` 加载 runtime，因此不要只放行 WASM 而漏掉 runtime 脚本。
+
+## 能力边界
+
+- `inspectGeometryKernelFile()` 仍可只读取文件前缀，识别 STEP / IGES / IFC / 3DM / BREP 常见签名。
+- STEP / STP、IGES / IGS 和 BREP 走 `occt-import-js` / OpenCascade，已经具备完整网格预览路径。
+- IFC 仍需要独立的 `web-ifc` / That Open 集成；3DM 仍需要 McNeel `rhino3dm` 集成。当前不会把它们伪装成已支持预览。
+- OCCT 与 `occt-import-js` 的许可证文件必须随离线资产一起分发。
+
+把重型几何能力留在独立包中，可以让 `@file-viewer/core` 保持轻量，同时隔离 Worker、WASM、许可证和真实工程样本回归边界。

package/assets/occt-worker.js

@@ -0,0 +1,83 @@
+'use strict';
+
+let runtimePromise = null;
+let runtimeKey = '';
+
+const normalizeMeshArrays = result => {
+  const transfer = [];
+  for (const mesh of result?.meshes || []) {
+    const position = Float32Array.from(mesh?.attributes?.position?.array || []);
+    mesh.attributes = mesh.attributes || {};
+    mesh.attributes.position = { array: position };
+    transfer.push(position.buffer);
+
+    if (mesh.attributes.normal?.array) {
+      const normal = Float32Array.from(mesh.attributes.normal.array);
+      mesh.attributes.normal = { array: normal };
+      transfer.push(normal.buffer);
+    }
+
+    const index = Uint32Array.from(mesh?.index?.array || []);
+    mesh.index = { array: index };
+    transfer.push(index.buffer);
+  }
+  return transfer;
+};
+
+const getRuntime = (runtimeUrl, wasmUrl) => {
+  const key = `${runtimeUrl}\n${wasmUrl}`;
+  if (runtimePromise && runtimeKey === key) {
+    return runtimePromise;
+  }
+  runtimeKey = key;
+  runtimePromise = Promise.resolve().then(() => {
+    if (typeof self.occtimportjs !== 'function') {
+      importScripts(runtimeUrl);
+    }
+    if (typeof self.occtimportjs !== 'function') {
+      throw new Error('The OCCT runtime did not expose occtimportjs().');
+    }
+    return self.occtimportjs({
+      locateFile(path) {
+        return path.endsWith('.wasm') ? wasmUrl : new URL(path, runtimeUrl).href;
+      },
+    });
+  });
+  runtimePromise.catch(() => {
+    runtimePromise = null;
+    runtimeKey = '';
+  });
+  return runtimePromise;
+};
+
+const readGeometry = (occt, format, bytes, params) => {
+  switch (format) {
+    case 'step':
+      return occt.ReadStepFile(bytes, params);
+    case 'iges':
+      return occt.ReadIgesFile(bytes, params);
+    case 'brep':
+      return occt.ReadBrepFile(bytes, params);
+    default:
+      throw new Error(`Unsupported OCCT geometry format: ${format}`);
+  }
+};
+
+self.addEventListener('message', async event => {
+  const { id, format, buffer, params, runtimeUrl, wasmUrl } = event.data || {};
+  try {
+    if (!id || !(buffer instanceof ArrayBuffer) || !runtimeUrl || !wasmUrl) {
+      throw new Error('Invalid geometry worker request.');
+    }
+    const occt = await getRuntime(runtimeUrl, wasmUrl);
+    const result = readGeometry(occt, format, new Uint8Array(buffer), params || null);
+    const transfer = normalizeMeshArrays(result);
+    self.postMessage({ id, ok: true, result }, transfer);
+  } catch (error) {
+    self.postMessage({
+      id,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+});

package/dist/index.d.ts

@@ -28,6 +28,52 @@ export interface GeometryKernelInspection {
     readonly signature?: string;
     readonly warnings: readonly string[];
 }
+export type GeometryOcctFormat = 'step' | 'iges' | 'brep';
+export type GeometryOcctLinearUnit = 'millimeter' | 'centimeter' | 'meter' | 'inch' | 'foot';
+export interface GeometryOcctImportParams {
+    linearUnit?: GeometryOcctLinearUnit;
+    linearDeflectionType?: 'bounding_box_ratio' | 'absolute_value';
+    linearDeflection?: number;
+    angularDeflection?: number;
+}
+export interface GeometryKernelArrayAttribute {
+    array: ArrayLike<number>;
+}
+export interface GeometryKernelFace {
+    first: number;
+    last: number;
+    color?: readonly number[] | null;
+}
+export interface GeometryKernelMesh {
+    name?: string;
+    color?: readonly number[];
+    brep_faces?: GeometryKernelFace[];
+    attributes: {
+        position: GeometryKernelArrayAttribute;
+        normal?: GeometryKernelArrayAttribute;
+    };
+    index: GeometryKernelArrayAttribute;
+}
+export interface GeometryKernelNode {
+    name?: string;
+    meshes: number[];
+    children: GeometryKernelNode[];
+}
+export interface GeometryKernelImportResult {
+    success: boolean;
+    root?: GeometryKernelNode;
+    meshes: GeometryKernelMesh[];
+}
+export interface ImportOcctGeometryOptions {
+    workerUrl?: string;
+    runtimeUrl?: string;
+    wasmUrl: string;
+    useWorker?: boolean;
+    timeoutMs?: number;
+    params?: GeometryOcctImportParams;
+    signal?: AbortSignal;
+}
+export declare const importOcctGeometryFile: (input: ArrayBuffer | Uint8Array, type: string, options: ImportOcctGeometryOptions) => Promise<GeometryKernelImportResult>;
 export declare const geometryKernelRoutes: readonly GeometryKernelRoute[];
 export declare const normalizeGeometryKernelFormat: (type?: string) => GeometryKernelFormat | undefined;
 export declare const getGeometryKernelRoute: (type?: string) => GeometryKernelRoute | undefined;

package/dist/index.js

@@ -1,3 +1,151 @@
+const DEFAULT_OCCT_IMPORT_TIMEOUT_MS = 120000;
+const occtRuntimePromises = new Map();
+let geometryWorkerRequestId = 0;
+const createGeometryAbortError = (signal) => {
+    if ((signal === null || signal === void 0 ? void 0 : signal.reason) instanceof Error) {
+        return signal.reason;
+    }
+    return new DOMException('Geometry import was aborted.', 'AbortError');
+};
+const toOwnedBytes = (input) => {
+    return input instanceof Uint8Array
+        ? input.slice()
+        : new Uint8Array(input.slice(0));
+};
+const normalizeOcctFormat = (type) => {
+    const format = normalizeGeometryKernelFormat(type);
+    if (format === 'step' || format === 'iges' || format === 'brep') {
+        return format;
+    }
+    throw new Error(`No OpenCascade import route is available for ${String(type || 'unknown').toUpperCase()}.`);
+};
+const validateOcctResult = (value, format) => {
+    const result = value;
+    if (!(result === null || result === void 0 ? void 0 : result.success)) {
+        throw new Error(`${format.toUpperCase()} geometry parsing failed. The file may be empty, damaged, or unsupported by this OpenCascade build.`);
+    }
+    if (!Array.isArray(result.meshes) || result.meshes.length === 0) {
+        throw new Error(`${format.toUpperCase()} geometry parsing completed without any renderable meshes.`);
+    }
+    return {
+        success: true,
+        root: result.root,
+        meshes: result.meshes,
+    };
+};
+const getOcctRuntime = (wasmUrl) => {
+    let promise = occtRuntimePromises.get(wasmUrl);
+    if (!promise) {
+        promise = import('occt-import-js')
+            .then(module => module.default({
+            locateFile(path) {
+                return path.endsWith('.wasm') ? wasmUrl : path;
+            },
+        }));
+        occtRuntimePromises.set(wasmUrl, promise);
+        promise.catch(() => occtRuntimePromises.delete(wasmUrl));
+    }
+    return promise;
+};
+const readOcctGeometry = (occt, format, bytes, params) => {
+    switch (format) {
+        case 'step':
+            return occt.ReadStepFile(bytes, params || null);
+        case 'iges':
+            return occt.ReadIgesFile(bytes, params || null);
+        case 'brep':
+            return occt.ReadBrepFile(bytes, params || null);
+    }
+};
+const importOcctGeometryOnMainThread = async (bytes, format, options) => {
+    var _a, _b, _c;
+    if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+        throw createGeometryAbortError(options.signal);
+    }
+    const runtime = await getOcctRuntime(options.wasmUrl);
+    if ((_b = options.signal) === null || _b === void 0 ? void 0 : _b.aborted) {
+        throw createGeometryAbortError(options.signal);
+    }
+    const result = readOcctGeometry(runtime, format, bytes, options.params);
+    if ((_c = options.signal) === null || _c === void 0 ? void 0 : _c.aborted) {
+        throw createGeometryAbortError(options.signal);
+    }
+    return validateOcctResult(result, format);
+};
+const importOcctGeometryInWorker = (bytes, format, options) => new Promise((resolve, reject) => {
+    var _a, _b;
+    if (!options.workerUrl || !options.runtimeUrl) {
+        reject(new Error('The OCCT worker and runtime URLs are required for worker-based geometry import.'));
+        return;
+    }
+    if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+        reject(createGeometryAbortError(options.signal));
+        return;
+    }
+    const worker = new Worker(options.workerUrl);
+    const requestId = `geometry-${Date.now()}-${++geometryWorkerRequestId}`;
+    const timeoutMs = Math.max(1000, options.timeoutMs || DEFAULT_OCCT_IMPORT_TIMEOUT_MS);
+    let settled = false;
+    const cleanup = () => {
+        var _a;
+        clearTimeout(timeout);
+        (_a = options.signal) === null || _a === void 0 ? void 0 : _a.removeEventListener('abort', onAbort);
+        worker.removeEventListener('message', onMessage);
+        worker.removeEventListener('error', onError);
+        worker.terminate();
+    };
+    const complete = (action) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        cleanup();
+        action();
+    };
+    const onAbort = () => complete(() => reject(createGeometryAbortError(options.signal)));
+    const onError = (event) => complete(() => reject(new Error(event.message || 'The OCCT geometry worker failed to load.')));
+    const onMessage = (event) => {
+        const message = event.data || {};
+        if (message.id !== requestId) {
+            return;
+        }
+        if (!message.ok) {
+            complete(() => reject(new Error(message.error || `${format.toUpperCase()} geometry parsing failed.`)));
+            return;
+        }
+        complete(() => {
+            try {
+                resolve(validateOcctResult(message.result, format));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    };
+    const timeout = setTimeout(() => complete(() => reject(new Error(`${format.toUpperCase()} geometry parsing timed out after ${Math.round(timeoutMs / 1000)} seconds.`))), timeoutMs);
+    (_b = options.signal) === null || _b === void 0 ? void 0 : _b.addEventListener('abort', onAbort, { once: true });
+    worker.addEventListener('message', onMessage);
+    worker.addEventListener('error', onError);
+    const transferableBuffer = bytes.buffer;
+    worker.postMessage({
+        id: requestId,
+        format,
+        buffer: transferableBuffer,
+        params: options.params || null,
+        runtimeUrl: options.runtimeUrl,
+        wasmUrl: options.wasmUrl,
+    }, [transferableBuffer]);
+});
+export const importOcctGeometryFile = async (input, type, options) => {
+    const format = normalizeOcctFormat(type);
+    const bytes = toOwnedBytes(input);
+    const canUseWorker = options.useWorker !== false &&
+        typeof Worker === 'function' &&
+        Boolean(options.workerUrl && options.runtimeUrl);
+    return canUseWorker
+        ? importOcctGeometryInWorker(bytes, format, options)
+        : importOcctGeometryOnMainThread(bytes, format, options);
+};
 const textDecoder = typeof TextDecoder === 'function'
     ? new TextDecoder('utf-8', { fatal: false })
     : undefined;
@@ -35,7 +183,7 @@ export const geometryKernelRoutes = [
             },
         ],
         serverConversionTargets: ['glb', 'gltf', 'stl', 'obj'],
-        licenseNotes: ['OCCT-based packages can have LGPL or custom distribution requirements; keep them opt-in.'],
+        licenseNotes: ['Ship the OCCT and occt-import-js license files beside the self-hosted runtime and WASM assets.'],
     },
     {
         format: 'iges',
@@ -187,6 +335,15 @@ export const formatGeometryKernelNotice = (type, locale = 'zh-CN') => {
     const formatLabel = (route === null || route === void 0 ? void 0 : route.label) || String(type || 'Engineering model').toUpperCase();
     const engines = (route === null || route === void 0 ? void 0 : route.recommended.map(item => item.packageName).join(' / ')) || 'OpenCascade / web-ifc / rhino3dm';
     const targets = (route === null || route === void 0 ? void 0 : route.serverConversionTargets.join(' / ')) || 'GLB / GLTF';
+    const hasNativeOcctPreview = (route === null || route === void 0 ? void 0 : route.format) === 'step' ||
+        (route === null || route === void 0 ? void 0 : route.format) === 'iges' ||
+        (route === null || route === void 0 ? void 0 : route.format) === 'brep';
+    if (hasNativeOcctPreview) {
+        if (locale === 'en-US') {
+            return `${formatLabel} is previewed locally with the dedicated OCCT Worker/WASM path. The file stays in the browser; configure options.model only when the self-hosted assets use a custom deployment path.`;
+        }
+        return `${formatLabel} 已通过独立 OCCT Worker/WASM 在浏览器本地完成预览，文件无需上传；仅当离线资源部署在自定义目录时，才需要覆盖 options.model 路径。`;
+    }
     if (locale === 'en-US') {
         return `${formatLabel} requires a dedicated WebAssembly geometry kernel (${engines}) for full browser preview. Flyfish Viewer keeps these heavy runtimes outside core and the default 3D renderer install path; use the dedicated geometry engine route or convert the model to ${targets} in a private pipeline.`;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@file-viewer/geometry-engine",
-  "version": "2.1.29",
+  "version": "2.2.0",
   "private": false,
   "type": "module",
   "description": "Framework-neutral geometry kernel boundary package for STEP, IGES, IFC, 3DM, and BREP preview routes in Flyfish File Viewer.",
@@ -52,6 +52,7 @@
   },
   "files": [
     "dist",
+    "assets",
     "README.md",
     "README.en.md",
     "LICENSE"
@@ -60,6 +61,9 @@
     "typescript": "^6.0.3"
   },
   "license": "Apache-2.0",
+  "dependencies": {
+    "occt-import-js": "0.0.23"
+  },
   "scripts": {
     "build": "tsc -b tsconfig.json",
     "type-check": "tsc -b tsconfig.json"