# 3D-printer

**Repository Path**: ns2250225/3D-printer

## Basic Information

- **Project Name**: 3D-printer
- **Description**: 3D打印机，上传图片打印为3D模型，可导出和下载
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LAYERA 3D Printer

一个以真实 3D 打印机为交互界面的图片转 3D Web 应用。用户上传参考图片后，项目调用腾讯混元 Hunyuan 3D 3.1 生成带 PBR 材质的 GLB 模型，并在 Three.js 场景中模拟逐层打印、预览和 STL 下载。

![界面与打印动画演示](./demo.gif)

## 功能特点

- 图片生成完整 3D 模型，而非二维浮雕
- 腾讯混元 `hy-3d-3.1` 图生 3D
- 自动轮询异步任务并下载 GLB
- GLB 本地缓存，相同图片无需重复生成
- Three.js 实时旋转、缩放和全屏预览
- 160 层水平裁切动画，模型按打印层逐渐显现
- 喷头、X 轴横梁、热床和料盘联动
- Ender 风格打印机机架、热端、皮带、弹簧热床和控制屏
- 将生成结果导出为二进制 STL
- 桌面端与移动端响应式布局

## 技术栈

- React 19
- Vite 8
- Three.js
- 腾讯混元 Hunyuan 3D TokenHub API
- Lucide React

## 本地运行

推荐使用 Node.js 20 或更高版本。

```bash
npm install --registry=https://registry.npmmirror.com
cp .env.example .env.local
```

在 `.env.local` 中填写腾讯云 TokenHub API Key：

```env
HUNYUAN_API_KEY=你的_TokenHub_API_Key
```

启动开发服务器：

```bash
npm run dev
```

浏览器访问：

```text
http://localhost:5173/
```

## 构建

```bash
npm run build
npm run preview
```

## 使用流程

1. 上传 JPG、PNG 或 WEBP 图片，建议主体完整、背景干净且占画面 50% 以上。
2. 点击“使用混元生成”。
3. 后端提交 `hy-3d-3.1` 图生 3D 任务并等待模型完成。
4. GLB 下载到本地缓存后，打印机开始逐层打印动画。
5. 可拖拽旋转、滚轮缩放、全屏预览或下载 STL。

## 环境变量

| 变量 | 必填 | 说明 |
| --- | --- | --- |
| `HUNYUAN_API_KEY` | 是 | 腾讯云 TokenHub API Key，仅在 Vite 服务端使用 |

密钥不会发送到浏览器，也不应提交到 Git。`.env.local` 已加入 `.gitignore`。

## 模型与缓存

- 默认模型：`hy-3d-3.1`
- PBR：开启
- 目标面数：150,000
- 输入图片上限：6 MB
- 任务最长等待时间：20 分钟
- 生成模型缓存在 `.hunyuan-cache/`
- 缓存目录不会提交到 Git

腾讯返回的模型下载地址具有时效性，因此后端会在任务完成后立即下载 GLB，再通过本地模型接口提供给 Three.js。

## 注意事项

- 调用腾讯混元 3D API 可能产生费用，请以腾讯云账户计费规则为准。
- 单图重建不可凭空获得完全准确的背面结构，建议使用轮廓清楚、遮挡较少的图片。
- STL 不包含 PBR 纹理；纹理材质仅用于网页 GLB 预览。
- 首次生成时间由腾讯任务队列和模型复杂度决定，相同图片再次生成会直接命中缓存。

## API 参考

- [腾讯混元 HY-3D 调用指南](https://cloud.tencent.com/document/product/1823/137181)
- [腾讯混元生 3D 产品文档](https://cloud.tencent.com/document/product/1804)