# @file-viewer/geometry-engine 中文文档

规范地址：https://npmcn.com/package/%40file-viewer/geometry-engine/

版本：3\.3\.3
npm 元数据更新时间：2026-10-31T11:06:35.275Z
中文译文更新时间：2026-11-14T17:42:20.015Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40file-viewer/geometry-engine
原文对照：https://npmcn.com/package/%40file-viewer/geometry-engine/?lang=original
项目主页：https://doc.file-viewer.app/guide/format-fidelity
源码仓库：https://github.com/flyfish-dev/file-viewer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：284 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-23T06:26:10.300Z
- 最新版本发布：2026-10-31T11:06:34.886Z
- 近 30 天下载量：36011（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 57 个）

## 中文简介

用于STEP,IGES,IFC,3DM,以及文件查看器中BREP预览路径的框架中立内核边界包.

## 安装

```sh
npm install @file-viewer/geometry-engine
```

也可以使用：`pnpm add @file-viewer/geometry-engine`、`yarn add @file-viewer/geometry-engine`、`bun add @file-viewer/geometry-engine`

## README

# @file-viewer/geometry-engine

[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/geometry-engine/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/geometry-engine/README.zh-CN.md)

Flyfish File Viewer 的无 UI、框架无关几何内核包。它已经提供浏览器原生的 STEP / STP、IGES / IGS 和 BREP 解析：文件在本地 OCCT Worker 中完成三角化，不需要上传或服务端转换。IFC 和 Rhino 3DM 目前只提供格式识别与准确的能力提示，尚未接入完整几何渲染。

```ts
import { importOcctGeometryFile } from '@file-viewer/geometry-engine'

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`，因为回退会占用主线程。

## 离线资产

运行时不访问 CDN。部署时需要把下列文件放到同一套静态资源中：

-   `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、许可证和真实工程样本回归边界。

## 常见问题

### @file-viewer/geometry-engine 是什么？

用于STEP,IGES,IFC,3DM,以及文件查看器中BREP预览路径的框架中立内核边界包\.

### 如何安装 @file-viewer/geometry-engine？

在项目目录运行 npm install @file-viewer/geometry-engine，或使用 pnpm add / yarn add / bun add。

### @file-viewer/geometry-engine 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @file-viewer/geometry-engine 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @file-viewer/geometry-engine 可以商用吗？

@file-viewer/geometry-engine 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @file-viewer/geometry-engine 的下载量有多少？

根据 npm 官方下载统计，@file-viewer/geometry-engine 在 2026/10/15 – 2026/11/13 这 30 天内被下载 36,011 次，日均约 1,200 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @file-viewer/geometry-engine 还在维护吗？

最新版本 3\.3\.3 发布于 2026/10/31（14 天前）；至今共发布 57 个版本，其中过去 12 个月发布了 57 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。