# Vector3D

**Repository Path**: SawyerJan14/vector3d

## Basic Information

- **Project Name**: Vector3D
- **Description**: Vector3D 是一款纯前端 PDF 转 3D 盒子模型工具，基于 Three.js 实现，支持贴图生成、交互调节及 GLTF 导出，开箱即用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-13
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BOX | 平面图转 3D 模型工具

一个基于 Web 的平面图转 3D 模型工具，可以将 PDF 文件转换为可交互的 3D 盒子模型，支持纹理贴图、光照调节和模型导出。

![版本](https://img.shields.io/badge/version-1.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Three.js](https://img.shields.io/badge/Three.js-r128-black)

## 📖 项目简介

BOX 是一个创新的 3D 模型生成工具，通过上传 PDF 平面图，自动识别并生成六面贴图，最终创建出带有真实纹理的 3D 盒子模型。项目采用纯前端技术栈，无需后端服务器，开箱即用。

## ✨ 功能特点

### 核心功能
- 📄 **PDF 导入** - 支持上传 PDF 文件，自动解析并提取页面
- 🎨 **六面贴图生成** - 自动生成盒子的六个面的贴图
- 🎯 **智能拖拽排序** - 支持拖拽调整六个面的顺序
- 📦 **3D 模型展示** - 基于 Three.js 的实时 3D 渲染
- 🔄 **模型交互** - 支持旋转、缩放、平移等操作
- 💡 **光照调节** - 可调节全局光照强度（0-1）
- 🎛️ **面旋转控制** - 每个面可独立旋转±90°
- 📥 **模型导出** - 支持导出 GLTF 格式的 3D 模型文件（JSON 格式，支持内嵌贴图）

### 技术亮点
- 🚀 **纯前端实现** - 无需后端，所有处理在浏览器完成
- 📱 **响应式设计** - 适配桌面和移动设备
- 🎨 **精美 UI** - 采用复古配色方案（深棕/金色/奶油色）
- ⚡ **性能优化** - 图片压缩、sessionStorage 会话管理
- 🔧 **灵活配置** - 光照、旋转等参数可实时调节

## 🛠️ 环境要求

### 系统要求
- Windows 10/11
- macOS 10.15+
- Linux (推荐 Ubuntu 20.04+)

### 浏览器要求
- Chrome 90+ (推荐)
- Firefox 88+
- Edge 90+
- Safari 14+

### 运行环境
- Python 3.8+ (用于本地服务器，可选)
- Node.js 16+ (可选，用于开发)

## 📦 安装步骤

### 方法一：直接运行（推荐）

1. **克隆项目**
```bash
git clone <your-repo-url>
cd Vector3D
```

2. **启动本地服务器**
```bash
# Windows
python -m http.server 80

# macOS/Linux
python3 -m http.server 80
```

3. **访问应用**
```
http://localhost:80/index.html
```

## 🚀 使用方法

### 基本流程

1. **上传 PDF/ai/eps 格式文件**
   - 打开 `http://localhost:80/index.htmll`
   - 点击"选择文件"按钮
   - 选择 PDF/ai/eps 格式 文件上传

![上传文件](item-img/step1.png)

2. **生成六面图**
   - 等待 PDF 解析完成
   - 自动生成六个面的贴图
   - 可拖拽调整面的顺序

![生成六面图](item-img/step2.png)

3. **生成 3D 模型**
   - 点击"转为 3D 模型"按钮
   - 自动跳转到 `viewer.html`
   - 查看 3D 模型效果

4. **调整模型**
   - **旋转**：鼠标拖拽旋转模型
   - **缩放**：鼠标滚轮缩放
   - **平移**：鼠标右键拖拽
   - **光照**：拖动光照强度滑块
   - **面旋转**：点击各面的旋转按钮

![生成 3D 模型](item-img/step3.png)

5. **导出模型**
   - 点击"下载 GLTF"按钮
   - 下载 `.gltf` 格式文件
   - 可使用window自带的 3D查看器 软件打开查看

![导出模型](item-img/step4.png)

### 快捷键

| 快捷键 | 功能 |
|--------|------|
| 鼠标左键拖拽 | 旋转模型 |
| 鼠标滚轮 | 缩放模型 |
| 鼠标右键拖拽 | 平移模型 |
| Ctrl + R | 刷新页面 |

## 📁 目录结构

```
Vector3D/
├── .gitignore              # Git 忽略文件配置
├── README.md               # 项目说明文档
├── index.html              # 主页面（文件上传和六面图生成）
├── viewer.html             # 3D 模型查看器页面
├── index-vue.html          # Vue 版本页面（可选）
├── package.json            # Node.js 依赖配置
├── package-lock.json       # Node.js 依赖锁定文件
├── vite.config.js          # Vite 构建配置
├── index.py                # Python 脚本（独立工具，可选）
├── src/                    # Vue 源码目录
│   ├── App.vue            # Vue 主组件
│   └── main.js            # Vue 入口文件
└── QUICK_TEST_GUIDE.md     # 快速测试指南（开发文档）
```

## 🎨 技术栈

### 前端核心
- **Three.js r128** - 3D 渲染引擎
- **PDF.js v3.4.120** - PDF 文件解析
- **Tailwind CSS** - 样式框架
- **Vue 3.4.0** (可选) - 前端框架

### 构建工具
- **Vite 5.x** - 前端构建工具
- **Python http.server** - 本地服务器（可选）

### 特性
- **WebGL** - 硬件加速 3D 渲染
- **SessionStorage** - 数据持久化（页面间传递数据）
- **Canvas API** - 图片处理
- **Blob API** - 文件导出
- **GLTFExporter** - 3D 模型导出

## ❓ 常见问题

### 1. 页面无法加载？

**解决方案：**
- 确保 Python 已安装：`python --version`
- 检查端口是否被占用：`netstat -ano | findstr :80`
- 尝试更换端口：`python -m http.server 8000`

### 2. PDF 上传后无响应？

**解决方案：**
- 检查 PDF 文件是否损坏
- 确保 PDF 文件不超过 10MB
- 查看浏览器控制台是否有错误信息

### 3. 3D 模型无法显示？

**解决方案：**
- 确保浏览器支持 WebGL
- 清除浏览器缓存（Ctrl + Shift + R）
- 检查 sessionStorage 是否被禁用

### 4. 下载的模型没有贴图？

**解决方案：**
- 确保使用了最新版本的代码
- 下载的是 `.gltf` 格式（JSON 格式，支持内嵌贴图）
- 检查文件大小（正常应 > 100KB）

### 5. 光照调节无效？

**解决方案：**
- 确保模型已完全加载
- 拖动滑块时观察数值变化
- 刷新页面重新生成模型

### 6. 图片方向不正确？

**解决方案：**
- 使用旋转控制面板调整每个面
- 左侧面默认向右旋转 90°
- 可自定义每个面的旋转角度

### 7. 导出的 GLTF 文件无法打开？

**解决方案：**
- 使用在线查看器验证：[gltf.report](https://gltf.report/)
- 确认文件扩展名是 `.gltf`（不是 `.glb`）
- 检查文件大小是否正常（200KB - 2MB）

## 🔧 开发指南

### 自定义配置

**修改默认光照强度：**
编辑 `viewer.html`，找到 `currentLightIntensity` 变量

**修改图片尺寸：**
编辑 `index.html`，找到 `scale` 参数（默认 150/72）

**修改盒子尺寸计算：**
编辑 `viewer.html` 中的 `createTexturedBox` 函数

### 测试导出功能

1. 生成 3D 模型后，点击"下载 GLTF"
2. 验证文件大小（应 > 100KB）
3. 使用在线查看器打开：
   - [gltf.report](https://gltf.report/)
   - [3D Viewer Online](https://3dviewer.net/)
   - [Babylon.js Sandbox](https://sandbox.babylonjs.com/)

## 📝 更新日志

### v1.0.0 (2026-04-13)
- ✨ 初始版本发布
- 🎨 支持 PDF 转 3D 模型
- 💡 添加光照调节功能
- 🎛️ 添加面旋转控制
- 📥 支持 GLTF 格式导出（JSON 格式，支持内嵌贴图）
- 📱 响应式设计优化
- 🚀 性能优化和 bug 修复

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📧 联系方式

如有问题或建议，请通过以下方式联系：
- 提交 Issue
- 发送邮件至：sawyerjan14@163.com

---

❤️ 用爱发电