# vectorfold **Repository Path**: atlaslee/vectorfold ## Basic Information - **Project Name**: vectorfold - **Description**: VectorFold 是一个专业级包装盒三维建模系统，实现从 2D SVG 盒型线框图到 3D 可折叠模型的智能转换。项目采用纯 TypeScript 技术栈，支持 Web 浏览器可视化编辑和 Node.js CLI 批量处理双平台运行。 - **Primary Language**: TypeScript - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-15 - **Last Updated**: 2026-06-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # VectorFold > 2D SVG 线框图 → 3D 折叠包装盒模型生成器 VectorFold 是一个专业级包装盒三维建模系统，实现从 2D SVG 盒型线框图到 3D 可折叠模型的智能转换。项目采用**纯 TypeScript 技术栈**，支持 Web 浏览器可视化编辑和 Node.js CLI 批量处理双平台运行。 --- ## 🎯 核心能力 | 能力 | 状态 | 说明 | |:-----|:----:|:-----| | SVG 解析 | ✅ | 多边形提取、线段重建、顶点焊接 | | 面片检测 | ✅ | 矩形/多边形识别、重叠面片自动裁剪 | | 折叠树构建 | ✅ | 基于共享边的拓扑分析、父子层级与深度计算 | | 3D 折叠动画 | ✅ | 刚体变换求解、完整 2775 行 FoldAnimator 引擎 | | Web 可视化编辑器 | ✅ | 2D SVG 编辑 + 3D 实时预览 | | Web Component 控件库 | ✅ | 4 个框架无关的 Custom Elements | | CLI 批量处理 | ✅ | 基于 Node.js 的命令行工具 | | 视频/图片导出 | ✅ | 微信格式 / MP4 / WebM / GIF / PNG | --- ## 🏗️ 系统架构 基于 [HLD 架构设计文档](./docs/design/high-level/architecture-HLD.md)，系统采用**双平台复用 + 渐进增强**原则： ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ VectorFold 系统架构 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────┐ ┌─────────────────────────────────┐ │ │ │ CLI 平台 (Node.js) │ │ Web 平台 (Browser) │ │ │ │ ┌─────────────────────────┐ │ │ ┌─────────────────────────┐ │ │ │ │ │ CLI Interface │ │ │ │ Web UI (React) │ │ │ │ │ │ - Commander.js │ │ │ │ - 2D Editor (SVG) │ │ │ │ │ │ - Batch processing │ │ │ │ - 3D Viewer (Three.js) │ │ │ │ │ └───────────┬─────────────┘ │ │ └───────────┬─────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ ┌───────────▼─────────────┐ │ │ ┌───────────▼─────────────┐ │ │ │ │ │ Core TypeScript Lib │ │ │ │ Core TypeScript Lib │ │ │ │ │ │ ┌─────────────────┐ │ │ │ │ ┌─────────────────┐ │ │ │ │ │ │ │ SVG Parser │ │◄──┼────┼──┤ │ SVG Parser │ │ │ │ │ │ │ │ Panel Detector │ │ │ │ │ │ Panel Detector │ │ │ │ │ │ │ │ OverlapResolver │ │ │ │ │ │ OverlapResolver │ │ │ │ │ │ │ │ Fold Tree Builder│ │ │ │ │ │ Fold Tree Builder│ │ │ │ │ │ │ │ Fold Animator │ │ │ │ │ │ Fold Animator │ │ │ │ │ │ │ └─────────────────┘ │ │ │ │ └─────────────────┘ │ │ │ │ │ └─────────────────────────┘ │ │ └─────────────────────────┘ │ │ │ │ │ │ │ │ │ │ ┌─────────────────────────┐ │ │ ┌─────────────────────────┐ │ │ │ │ │ File System │ │ │ │ Browser APIs │ │ │ │ │ │ - SVG files │ │ │ │ - File System Access │ │ │ │ │ │ - Project JSON │ │ │ │ - LocalStorage │ │ │ │ │ │ - Export (OBJ/MP4) │ │ │ │ - WebGL (Three.js) │ │ │ │ │ └─────────────────────────┘ │ │ └─────────────────────────┘ │ │ │ └─────────────────────────────────┘ └─────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 共享数据格式 │ │ │ │ SVG → Polygons → Panels → FoldData → 3D Mesh → Export(OBJ/MP4) │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` > 设计决策：核心算法完全由 TypeScript 实现，不再依赖 Python / Pyodide。这使得部署更轻量（无需加载 ~20-30MB WASM 运行时），同时保证 CLI 和 Web 100% 代码共享。 --- ## 📦 项目结构 ``` vectorfold/ ├── packages/ │ ├── core/ # @vectorfold/core — 纯 TS 核心算法 │ │ ├── src/parse/ # SVG 解析器 │ │ ├── src/fold/ # 折叠检测、树构建、刚体求解、动画器 │ │ └── dist/ # 构建产物 (ESM) │ └── web-component/ # @vectorfold/web-component — 框架无关控件 │ ├── src/components/ # 4 个 Custom Elements │ ├── src/renderers/ # Three.js 渲染器 (FoldPreviewRenderer 等) │ └── dist/ # 构建产物 (ESM + UMD) │ ├── web/ # React 18 + Vite 5 可视化编辑器 Demo │ ├── src/ │ │ ├── components/ # React 组件 │ │ ├── store/ # Zustand + Immer 状态管理 │ │ ├── hooks/ # React Hooks │ │ ├── types/ # TypeScript 类型 │ │ └── App.tsx # 主入口（已改用 Web Component） │ └── package.json │ ├── cli/ # Node.js CLI 工具 │ ├── src/commands/ # 命令实现 │ └── README.md # CLI 使用文档 │ ├── docs/ # 设计文档与使用文档 │ ├── design/ # HLD / LLD / 评审报告 │ ├── planning/ # 里程碑 / WBS / 进度 / 风险 / 质量计划 │ ├── requirements/ # 需求规格 │ ├── getting-started.md # 快速开始 │ ├── core-api.md # Core API 文档 │ └── web-component-api.md # Web Component API 文档 │ ├── downloads/ # SVG 数据集下载目录 └── examples/ # 使用示例 ``` --- ## 🚀 快速开始 ### 环境要求 - Node.js >= 18 - npm >= 9 ### 1. 安装并构建核心库 ```bash cd packages/core npm install npm run build cd ../web-component npm install npm run build ``` ### 2. 启动 Web 编辑器 Demo ```bash cd ../../web npm install npm run dev ``` 浏览器打开 http://localhost:3000/ 即可使用。 ### 3. 使用 CLI ```bash cd ../cli npm install npm link # 查看命令 vectorfold --help ``` 更详细的安装和使用说明请参考： - [快速开始文档](./docs/getting-started.md) - [Core API 文档](./docs/core-api.md) - [Web Component API 文档](./docs/web-component-api.md) --- ## 🧩 Web Component 控件一览 `@vectorfold/web-component` 提供 4 个可直接在 HTML / React / Vue / Angular 中使用的 Custom Elements： | 控件 | 用途 | 核心特性 | |:-----|:-----|:---------| | `` | 一体化查看器 | 传入 SVG 即可直接出 3D，支持 `src`、`angle`、`wireframe` 等属性 | | `` | 2D SVG 编辑器 | 网格、面片、线段高亮、滚轮缩放、拖拽平移 | | `` | 3D 折叠预览器 | 动画播放/暂停/进度条、透视/正交投影、自动旋转、录制导出 | | `` | 折叠生成面板 | V1/V2 算法切换、生成统计、面片结构列表 | ### React 中使用示例 ```tsx import '@vectorfold/web-component'; export default function App() { return ( ); } ``` > 注意：目前包**尚未发布到 npm 官方仓库**，外部项目需要通过本地路径或自行 publish 后安装。详见 [快速开始文档](./docs/getting-started.md)。 --- ## 🧠 核心算法模块 `@vectorfold/core` 的关键模块和设计文档对应关系： | 模块 | 设计文档 | 功能 | |:-----|:---------|:-----| | `SVG Parser` | [module-svg-parser-LLD](./docs/design/detailed/core/module-svg-parser-LLD.md) | 从 SVG 提取多边形与线段 | | `PanelDetector` | [module-fold-detector-LLD](./docs/design/detailed/core/module-fold-detector-LLD.md) | 矩形/多边形面片识别 | | `OverlapResolver` | [algo-fold-detection-LLD](./docs/design/detailed/algorithm/algo-fold-detection-LLD.md) | 重叠面片裁剪与过滤 | | `FoldTreeBuilder` | [algo-3d-folding-LLD](./docs/design/detailed/algorithm/algo-3d-folding-LLD.md) | 基于共享边构建折叠树与深度层级 | | `RigidSolver` | [algo-geometry-utils-LLD](./docs/design/detailed/algorithm/algo-geometry-utils-LLD.md) | 刚体变换矩阵与四元数计算 | | `FoldAnimator` | [algo-3d-folding-LLD](./docs/design/detailed/algorithm/algo-3d-folding-LLD.md) | 2775 行完整 3D 折叠动画引擎 | --- ## 📋 功能实现状态 ### 已完成功能 ✅ - **M0**: 项目脚手架、核心包结构、类型系统 - **M1**: SVG 解析器、顶点焊接、统一数据模型 - **M2**: 折叠线检测（Topology/Geometry/Heuristic 策略）、置信度评分、山折/谷折推断 - **M3**: 四元数/矩阵转换、折叠树构建、递归变换、增量重计算、3D 顶点焊接 - **M4**: 三角形化（耳切法）、UV 映射、法线计算、OBJ / GLTF 导出器 - **M5**: SVGView (2D 编辑器)、ThreeView (3D 预览)、状态管理 (Zustand) - **M6**: UI 面板、属性编辑、撤销重做、2D/3D 同步机制 - **Web Component 化**: 核心算法与 UI 控件彻底解耦，形成可复用的 `@vectorfold/web-component` 包 - **CLI 工具**: 完整的命令行入口（下载、解析、导出等） ### 进行中 / 待完善 🚧 - SVG 远程 API 批量下载（因服务端暂时不可用，已下载 23,744 张后暂停） - 更多盒型的算法验证与自动测试覆盖 --- ## 📚 文档导航 ### 设计文档 | 文档 | 说明 | |:-----|:-----| | [architecture-HLD.md](./docs/design/high-level/architecture-HLD.md) | 系统总体架构（双平台、模块划分、数据流） | | [algorithm-geometry-HLD.md](./docs/design/high-level/algorithm-geometry-HLD.md) | 折叠线识别与 3D 几何计算设计 | | [frontend-editor-HLD.md](./docs/design/high-level/frontend-editor-HLD.md) | 前端编辑器架构（2D/3D 同步、状态管理） | | [FINAL_DESIGN_APPROVAL.md](./docs/design/FINAL_DESIGN_APPROVAL.md) | 详细设计最终审批报告 | ### 规划文档 | 文档 | 说明 | |:-----|:-----| | [planning/README.md](./docs/planning/README.md) | 项目规划总览 | | [MILESTONE_INDEX.md](./docs/planning/MILESTONE_INDEX.md) | M0-M9 里程碑索引 | | [schedule/project-schedule.md](./docs/planning/schedule/project-schedule.md) | 甘特图与进度计划 | | [risk/risk-management-plan.md](./docs/planning/risk/risk-management-plan.md) | 风险管理计划 | | [quality/quality-plan.md](./docs/planning/quality/quality-plan.md) | 质量计划与测试策略 | ### 开发文档 - [快速开始](./docs/getting-started.md) - [Core API 参考](./docs/core-api.md) - [Web Component API 参考](./docs/web-component-api.md) - [CLI 文档](./cli/README.md) --- ## 🛠️ 开发规范 - **TypeScript**: 启用严格类型检查 (`strict: true`) - **代码风格**: Prettier 格式化 + ESLint 检查 - **测试**: Vitest 单元测试，核心模块覆盖率目标 > 90% - **Git 提交**: 遵循 Conventional Commits 规范 --- ## 📄 许可证 MIT License --- ## 🤝 贡献 欢迎提交 Issue 和 Pull Request。如需了解当前任务状态，请查阅 [docs/planning/](./docs/planning/) 目录下的里程碑与 WBS 文档。