# @comfyorg/quad-wireframe-three 中文文档

规范地址：https://npmcn.com/package/%40comfyorg/quad-wireframe-three/

版本：0\.1\.0
npm 元数据更新时间：2026-11-01T18:51:24.418Z
中文译文更新时间：2026-11-10T11:45:59.470Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40comfyorg/quad-wireframe-three
原文对照：https://npmcn.com/package/%40comfyorg/quad-wireframe-three/?lang=original
项目主页：https://comfy.org/
源码仓库：https://github.com/Comfy-Org/quad-wireframe-three

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

- 包体积（解压后）：111 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- peer 依赖：three \>=0\.160\.0
- 首次发布：2026-09-22T02:35:43.860Z
- 最新版本发布：2026-09-22T02:35:44.284Z
- 近 30 天下载量：269973（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

Polygon (quad/n-gon) topology for three.js meshes——从二进制FBX读出面相大小,用Blender的"三相相"算法从三角汤中重建出四相,并画出没有三角对角的线框.

## 安装

```sh
npm install @comfyorg/quad-wireframe-three
```

也可以使用：`pnpm add @comfyorg/quad-wireframe-three`、`yarn add @comfyorg/quad-wireframe-three`、`bun add @comfyorg/quad-wireframe-three`

## README

# 校对:soup

三.js meshes的多边形地貌:绘制显示的线框 **以正角和正角代替三角对角**。 。 。 .

3.j只知道三角形. `material.wireframe = true` 画出每个三角形的每一个边缘,所以一个四相网(重构字符,Tripo/Messy"quad"输出,Blender的任何出处)通过每个面相出现一对角. `EdgesGeometry` 无法修复它:在非平面四面体上,对角具有像真边缘一样的二面体角. 此软件包还原了多边形,只绘制了它们的周边.

两种方式:

| 来源 | 方法 | 准确性 |
| --- | --- | --- |
| **二进制 FBX** | 直接读取面额大小 `PolygonVertexIndex`,然后重新组合三角形 `FBXLoader` 发射. | 准确(文件有数据). |
| **glTF 为 `FB_ngon_encoding`** | 解码扩展规定的风扇排序索引缓冲器(Nomad Scult and Assimpt write it). | 准确(顺序为数据). |
| **GLB / OBJ / STL / 任何东西** | 重建带有 Blender 端口的四边形 _三进制到四进制_ (单位:千美元)`bmo_join_triangles`),四质量上最先合并. | 大约98%的原始边缘 在一个吵闹的回波网. |

输出为平面 `PolygonMesh` (组合位置+相相抵,布局相同Blender使用)和a `BufferGeometry` 准备 `THREE.LineSegments`。 。 。 .

## 安装

```sh
npm install @comfyorg/quad-wireframe-three three
```

## 使用量

### GLB 或任何三角几何

```ts
import { LineBasicMaterial, LineSegments } from 'three'
import { createQuadWireframeGeometry } from '@comfyorg/quad-wireframe-three'

const wire = new LineSegments(
  createQuadWireframeGeometry(mesh.geometry),
  new LineBasicMaterial({ color: 0xffffff })
)
mesh.add(wire)
```

`createQuadWireframeGeometry` 焊接顶点,运行 Blender 三相向四相融合并返回多边形边缘。 调试或禁用合并 :

```ts
createQuadWireframeGeometry(geometry, { join: false }) // plain triangle edges
createQuadWireframeGeometry(geometry, {
  join: {
    faceAngleThreshold: (60 * Math.PI) / 180, // Blender "Max Face Angle", default 40°
    shapeAngleThreshold: (60 * Math.PI) / 180, // Blender "Max Shape Angle", default 40°
    topologyInfluence: 2 // Blender "Topology Influence" 0..2, default 1
  }
})
```

### FBX (精确的多边形)

```ts
import { FBXLoader } from 'three/examples/jsm/loaders/FBXLoader.js'
import {
  createQuadWireframeGeometry,
  matchFbxPolygons,
  readFbxPolygons
} from '@comfyorg/quad-wireframe-three'

const buffer = await (await fetch(url)).arrayBuffer()
const root = new FBXLoader().parse(buffer, '')
const polygons = readFbxPolygons(buffer)

root.traverse((child) => {
  if (!(child as Mesh).isMesh) return
  const mesh = child as Mesh
  const faceSizes = matchFbxPolygons(polygons, mesh.geometry)
  const wire = createQuadWireframeGeometry(mesh.geometry, { faceSizes })
  mesh.add(new LineSegments(wire, material))
})
```

为什么一个单独的读者 而不是 `FBXLoader`: 加载器分析 `PolygonVertexIndex`不过 `genFace` 耳切每个多边形,只推出三角形顶点,所以平面顶点计数从不存储在输出的任何地方;以及它的顶点计数 `BinaryParser` 被解析的树是私有的单元(`FBXLoader.js` 仅出口 `FBXLoader`)),所以也没有钩子读取. `readFbxPolygons` 因此,它本身是一个小型的二进制FBX读取器(zlib数组通过 `fflate`,同一图书馆 `FBXLoader` 用于) `Objects/Geometry/PolygonVertexIndex` 并跳过纹理,动画和其他一切;它不解析ASCII FBX. `matchFbxPolygons` 以名称标注有 3.js 几何的相配记录 `FBXLoader` 复制到上面,返回到一个独特的三角点,然后返回 `null` 当它无法确定时——通过 `faceSizes: null` 和几何重建运行.

### glTF 为 `FB_ngon_encoding`

glTF 本身没有多边形, 但草稿 [`FB_ngon_encoding`](https://github.com/KhronosGroup/glTF/pull/1620) 扩展按三角顺序编码它们:每个多边形都是以一个顶点为锚的扇形,相接的多边形从不共享锚地,所以多边形边界在任何地方都存在 `triangle.vertex[0]` 变化. `GLTFLoader` 保存索引顺序并记录国旗 `mesh.userData.gltfExtensions`数字 :

```ts
import { hasNgonEncoding, ngonEncodedFaceSizes } from '@comfyorg/quad-wireframe-three'

const faceSizes = hasNgonEncoding(mesh) ? ngonEncodedFaceSizes(mesh.geometry) : null
const wire = createQuadWireframeGeometry(mesh.geometry, { faceSizes })
```

只有在旗帜出现时才解码:在一个没有悬挂标记的网格上,偶然共享第一个索引的相邻三角会被错误地合并. 任何重新排序索引(德拉克语,meshopt语,多为optimisers语)都会破坏编码,并随之降下国旗.

### 下层棋子

```ts
import {
  polygonMeshFromTriangles, // BufferGeometry (+ optional faceSizes) → PolygonMesh
  joinTriangles, // Blender Tris to Quads on a PolygonMesh
  polygonEdges, // unique [a, b, a, b, ...] vertex pairs
  createPolygonEdgesGeometry, // PolygonMesh → LineSegments geometry
  faceSizesOf, // per-face vertex counts (3 = tri, 4 = quad, ...)
  weldPositions,
  parseBinaryFbx
} from '@comfyorg/quad-wireframe-three'
```

`faceSizesOf` 这也是你如何变得诚实 _脸_ 统计(Blender's "Faces" 而不是三角计数)用于加载模型.

## 业绩

焊接使用字符串密钥映射,合并为 `O(E log E)`两者都以普通JS的主线运行. 数十万个三角形的梅谢斯,跑 `polygonMeshOf` 在工人中,并传输所产生的打出数组.

## 常见问题

### @comfyorg/quad-wireframe-three 是什么？

Polygon \(quad/n-gon\) topology for three\.js meshes——从二进制FBX读出面相大小,用Blender的"三相相"算法从三角汤中重建出四相,并画出没有三角对角的线框\.

### 如何安装 @comfyorg/quad-wireframe-three？

在项目目录运行 npm install @comfyorg/quad-wireframe-three，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：three（\>=0\.160\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @comfyorg/quad-wireframe-three 支持 TypeScript 吗？

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

### @comfyorg/quad-wireframe-three 支持 ESM 还是 CommonJS？

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

### @comfyorg/quad-wireframe-three 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @comfyorg/quad-wireframe-three 可以商用吗？

@comfyorg/quad-wireframe-three 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @comfyorg/quad-wireframe-three 的下载量有多少？

根据 npm 官方下载统计，@comfyorg/quad-wireframe-three 在 2026/10/11 – 2026/11/09 这 30 天内被下载 269,973 次，日均约 8,999 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @comfyorg/quad-wireframe-three 还在维护吗？

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