Origami计算折纸项目故障排除指南

[安装失败与依赖冲突]如何解决？

问题定位

安装Origami库时常见症状包括：npm安装时报错"依赖版本不兼容"、浏览器引入时控制台提示"未找到模块"、运行测试用例时出现"模块缺失"错误。这些问题通常与Node.js环境配置、包管理器缓存或网络连接有关。

核心原理

Origami采用模块化架构，通过rollup.config.js配置打包流程，package.json中声明了对特定版本依赖的要求。安装过程本质是建立符合版本约束的依赖树，任何版本不匹配都会导致安装失败。

解决方案

🔍 排查步骤

1. 检查Node.js版本：node -v（要求≥14.0.0）
2. 查看npm缓存状态：npm cache verify
3. 检查网络连接是否正常访问npm仓库

🛠️ 实施方法

# 方案1：标准安装流程
npm install rabbit-ear

# 方案2：强制清除缓存后安装
npm cache clean --force && npm install rabbit-ear

# 方案3：指定版本安装（针对版本冲突）
npm install rabbit-ear@latest

✅ 验证方式

# 运行测试套件验证安装完整性
npm test

原理剖析

Origami的安装机制基于npm的语义化版本控制(SemVer)，package.json中"dependencies"字段指定了兼容的版本范围。当安装失败时，通常是因为环境中存在不兼容的依赖版本，或npm未能正确解析依赖树。

常见误区

• ❌ 使用sudo npm install导致权限问题
• ❌ 同时使用npm和yarn管理依赖
• ❌ 忽略Node.js版本要求，使用过旧版本

解决方案对比

解决方案	适用场景	复杂度	成功率
标准安装	全新环境	低	90%
清除缓存安装	依赖冲突	中	95%
指定版本安装	版本特定问题	中	98%

[FOLD文件解析错误]如何解决？

问题定位

FOLD文件解析错误表现为：加载模型时抛出"JSON解析失败"、控制台显示"缺失必填字段"或"坐标格式错误"。这些问题根源在于FOLD文件不符合FOLD规范定义的JSON结构。

核心原理

FOLD格式是计算折纸的标准化数据结构，采用JSON格式存储折纸模型的顶点、边、面等几何信息及折痕分配。解析过程涉及JSON验证和结构完整性检查，任何不符合规范的字段或值都会导致解析失败。

解决方案

🔍 排查步骤

1. 验证JSON格式合法性：使用JSONlint等工具检查语法
2. 检查核心字段完整性：确保包含vertices_coords、edges_vertices等必填项
3. 确认数据类型正确：坐标应为数字数组，引用应为整数索引

🛠️ 实施方法

// 使用 Origami 内置的 FOLD 验证工具
const origami = require('rabbit-ear');
const foldData = require('./your-model.fold');
const validation = origami.axioms.validate(foldData);
if (!validation.valid) {
  console.error("Validation errors:", validation.errors);
}

✅ 验证方式 通过convert/foldToSvg.js模块尝试转换为SVG，若成功渲染则表示解析正常：

const svg = origami.convert.foldToSvg(foldData);
console.log(svg); // 输出SVG字符串表示成功

原理剖析

Origami的FOLD解析器在axioms/validate.js中实现，通过递归检查JSON结构、数据类型和引用完整性来验证文件合法性。解析过程分为语法验证和语义验证两个阶段，前者检查JSON格式，后者确保几何数据逻辑一致。

常见误区

• ❌ 手动编辑FOLD文件时修改了关键结构
• ❌ 忽略frame字段导致动画数据解析错误
• ❌ 使用非标准折痕类型（只能使用"M"、"V"、"F"、"U"）

解决方案对比

解决方案	适用场景	复杂度	成功率
JSON语法检查	格式错误	低	85%
核心字段验证	结构缺失	中	90%
完整语义验证	逻辑错误	高	98%

[SVG渲染异常]如何解决？

问题定位

SVG渲染异常表现为：图形错位、元素缺失、样式混乱或坐标系错误。这些问题通常与视图框配置、几何转换或样式冲突有关，可通过浏览器开发者工具检查SVG元素属性进行诊断。

核心原理

Origami的SVG渲染系统在svg/constructor/elements.js中实现，通过构建SVG DOM元素并应用几何变换来可视化折纸模型。渲染过程涉及坐标系统转换、样式应用和元素层次管理三个关键环节。

解决方案

🔍 排查步骤

1. 检查视图框设置：确认viewBox属性是否正确反映模型尺寸
2. 验证坐标转换：使用math/transform.js检查变换矩阵
3. 审查样式定义：通过svg/stylesheets.js检查是否存在CSS冲突

🛠️ 实施方法

// 正确配置SVG视图框
const svgOptions = {
  viewBox: [-100, -100, 200, 200], // [x, y, width, height]
  strokeWidth: 0.5,
  fill: "#ffffff"
};
// 使用平面化处理复杂模型
const planarGraph = origami.graph.planarize(origamiGraph);
const svg = origami.convert.foldToSvg(planarGraph, svgOptions);

✅ 验证方式 将生成的SVG字符串保存为文件，在浏览器中打开检查：

• 确认模型居中显示
• 检查折痕线条清晰无重叠
• 验证面填充颜色正确

原理剖析

SVG渲染的核心是convert/foldToSvg.js模块，它将FOLD格式数据转换为SVG元素。转换过程中，首先通过graph/planarize.js处理几何数据确保平面化，然后应用坐标变换将模型映射到SVG视图空间，最后添加样式信息完成渲染。

常见误区

• ❌ 忽略视图框设置导致模型缩放异常
• ❌ 未进行平面化处理复杂模型导致重叠
• ❌ 自定义样式覆盖了默认SVG属性

解决方案对比

解决方案	适用场景	复杂度	成功率
调整视图框	模型位置异常	低	90%
平面化处理	图形重叠	中	85%
样式重置	视觉异常	低	95%

[折纸算法返回空结果]如何解决？

问题定位

当调用Kawasaki定理、Maekawa定理等核心算法返回空结果时，通常表现为函数返回null或空数组。这类问题多与输入数据的几何特性或拓扑结构有关，需从顶点度数、折痕分配和计算精度三方面排查。

核心原理

Origami的折纸算法基于计算几何和图论原理，如Kawasaki定理要求单顶点周围的角序列满足交替和为零，Maekawa定理则规定山折与谷折数量差为±2。算法实现位于singleVertex/目录，通过几何计算验证这些定理条件。

解决方案

🔍 排查步骤

1. 检查顶点度数：Kawasaki定理要求顶点度数为偶数
2. 验证折痕分配：确保折痕类型分配无矛盾
3. 调整计算精度：修改math/constant.js中的epsilon值

🛠️ 实施方法

// 检查单顶点可折叠性
const vertexIndex = 0;
const isFlatFoldable = origami.singleVertex.flatFoldable(origamiGraph, vertexIndex);
if (!isFlatFoldable) {
  // 分析原因
  const degrees = origami.graph.vertices.degree(origamiGraph, vertexIndex);
  console.log("顶点度数:", degrees);
  const angles = origami.graph.vertices.angles(origamiGraph, vertexIndex);
  console.log("角度序列:", angles);
}

✅ 验证方式 使用测试用例中的标准模型验证算法功能：

// 加载测试模型
const testModel = require('../tests/files/fold/bird-base.fold');
// 验证Kawasaki定理
const result = origami.singleVertex.kawasaki(testModel, 0);
console.log("Kawasaki检查结果:", result); // 应为true

原理剖析

以Kawasaki定理实现为例，singleVertex/kawasaki.js通过以下步骤工作：

1. 计算顶点周围的角度序列
2. 验证角度数量是否为偶数
3. 检查交替角度和是否为π弧度
4. 返回布尔结果或角度调整建议

算法使用math/constant.js中定义的epsilon值处理浮点计算误差，默认值为1e-6，可根据需要调整。

常见误区

• ❌ 对非单顶点模型应用单顶点定理
• ❌ 忽略角度计算的数值精度问题
• ❌ 未处理共线顶点导致的拓扑异常

解决方案对比

解决方案	适用场景	复杂度	成功率
顶点度数检查	输入拓扑错误	低	80%
折痕分配验证	折痕类型冲突	中	85%
精度调整	浮点计算误差	中	90%

[文档与资源获取]如何解决？

问题定位

用户常面临找不到合适学习资源、示例代码或API文档的问题。这影响开发效率，尤其对新用户理解项目结构和核心功能造成障碍。

核心原理

Origami项目采用自文档化设计，代码注释、测试用例和结构化目录共同构成了学习资源体系。项目文档遵循"代码即文档"理念，核心算法和API在源代码中有详细注释。

解决方案

🔍 排查步骤

1. 确认本地文档生成状态：检查是否存在docs/目录
2. 验证测试用例完整性：查看tests/files/fold/中的示例模型
3. 检查TypeScript类型定义：确认src/libTypes.d.ts是否存在

🛠️ 实施方法

# 生成本地文档
npm run docs

# 运行示例测试
npm test -- --grep "singleVertex"

# 浏览TypeScript类型定义
cat src/libTypes.d.ts

✅ 验证方式

• 访问生成的docs/index.html确认文档完整性
• 运行特定测试用例验证功能理解：npm test graph.planarize.test.js
• 检查TypeScript类型提示是否正常工作

原理剖析

Origami使用typedoc生成API文档，配置文件为typedoc.config.json。文档生成过程从源代码中提取JSDoc注释，结合TypeScript类型定义，生成结构化的HTML文档。测试用例不仅用于验证功能，也作为使用示例存在。

常见误区

• ❌ 忽视测试用例中的示例代码
• ❌ 未利用TypeScript类型定义辅助开发
• ❌ 不知道可以通过npm run docs生成本地文档

解决方案对比

解决方案	适用场景	复杂度	信息完整度
生成本地文档	API查询	低	高
分析测试用例	使用示例	中	中
阅读源代码	深入理解	高	最高

技术资源导航

入门级资源

• 安装指南：项目根目录readme.md
• 基础示例：tests/files/fold/目录下的标准模型
• 核心概念：src/fold/spec.js中的FOLD格式定义

进阶级资源

• API文档：通过npm run docs生成本地文档
• 算法实现：src/singleVertex/目录下的折纸定理实现
• 转换工具：src/convert/目录下的格式转换模块

专家级资源

• 数学基础：src/math/目录下的计算几何算法
• 渲染系统：src/webgl/目录下的3D渲染实现
• 测试套件：tests/目录下的完整测试用例

问题反馈

如果您遇到本指南未覆盖的问题场景，请通过以下方式提交反馈：

1. 详细描述：问题现象、复现步骤和预期结果
2. 环境信息：Node.js版本、操作系统和浏览器类型
3. 错误日志：控制台输出或错误堆栈信息
4. 测试用例：如有可能，提供最小化的复现模型

您的反馈将帮助我们持续完善这份故障排除指南，共同改进Origami计算折纸项目的用户体验。