wehub-resource-sync
7.7 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
3D Model Studio
AI 驱动的交互式 3D 模型生成、检查和演示工作台。
3D Model Studio 是一个 React + Three.js 原型，用于把上传图片或 GLB 文件变成可交互的 3D 模型工作区。它支持 WebGL 拖拽旋转、滚轮缩放、左侧模型库 / 中央 3D 舞台 / 右侧工具区、截图、GLB 导出、历史上传默认收起、Demo 演示模式、生成队列，以及通过 Hyper3D / Tripo / Fal.ai / Hunyuan3D / JS Depth / 本地模型导入生成或加载 3D 模型。
演示视频
打开视频文件：演示 MP4
功能
- 基于 React Three Fiber 的交互式模型查看器。
- 三栏工作台：左侧 Model Library，中间 WebGL 主舞台，右侧素材和生成工具。
- 支持拖拽旋转、滚轮缩放、结构隔离、部件 Inspect 和场景导出。
- 对象级说明面板会根据资产名称和生成元数据推断类别、来源、Provider 状态、材质重点、演示价值和标签，覆盖车辆、飞机、船舰、产品、文物和有机标本。
- 模型质量评分会展示 GLB 文件大小、三角面数、贴图数量和演示可用性。
- Demo Mode 会隐藏左右工具区、根据物体类型使用不同运镜，并显示干净的演示信息层，适合截图和录屏。
- Model Library 抽屉升级为资产库视图，包含源图预览、Provider / 状态、任务 ID、GLB URL 操作、Provider 对比和删除入口。
- Saved Assets 默认收起，当前激活的生成 / 导入资产会固定显示并可直接点击打开。
- 生成 / 导入成功的模型会写入 IndexedDB，刷新页面后会自动恢复；localStorage 只做轻量兜底。
- 自定义上传记录支持删除，并同步清理相关本地数据。
- 通用部件详情抽屉、素材参考、对比面板、模型笔记、图库操作、日志、项目保存和生成队列。
- 支持 Hyper3D、Tripo、Fal.ai、Hunyuan3D、JS Depth 和 Local GLB 多种模式。
- 生成后的 GLB 会缓存到本地，方便后续演示和截图。
- 内置 Khronos glTF 辅助参考模型，用于检查 GLB 加载和 PBR 材质表现。
- API Key 只放在服务端
.env.local，不会暴露到前端包里。
技术栈
- React
- Vite
- Three.js
- React Three Fiber
- Drei
- Framer Motion
- Tripo API 可选后端
- Fal.ai 可选后端
- Hunyuan3D 本地 API 可选后端
快速开始
npm install
npm run dev
打开终端里显示的 Vite 地址即可。
工作台流程
默认页面会尽量减少干扰：
- 左侧
Model Library固定展示当前激活的生成 / 导入资产。 - 更早生成、导入过的模型会收进
Saved Assets，默认折叠。 - 右侧
Asset Source用来选择生成模式或导入本地.glb/.gltf。 - 左侧
Generation Queue可以查看上传、生成、导入状态，并对失败任务重试。 - 需要部件说明时，再点击
Info或Inspect打开详情抽屉。 - 顶部打开
Library可以查看完整资产库：预览、Provider 状态、任务 ID、GLB URL 复制、Provider 对比和删除。 - 顶部点击
Demo进入纯展示模式，适合截图、录屏、演示。 - 录屏前先看主舞台的质量评分；分数低通常说明源图或生成结果还不适合演示。
- Demo 动画会根据模型名称和元数据切换：汽车走低机位推进，飞机走飞行掠过，航母 / 船走侧向巡航，有机 / 标本类资产走工作室环绕。
常用验证命令：
npm run lint
npm run build
npm run test
npm run test:visual
npm run test:visual 会运行 Playwright 布局和截图回归，覆盖工作台、Model Library 抽屉和 Demo Mode。只有确认 UI 改动是预期变化时，才运行 npm run test:visual:update 更新截图基线。
可选 Image-to-3D 后端
创建 .env.local：
cp .env.example .env.local
然后设置：
TRIPO_API_KEY=your_tripo_key
FAL_API_KEY=your_fal_key
RODIN_API_KEY=your_rodin_api_key
OPENAI_API_KEY=your_openai_key
API_HOST=127.0.0.1
OPENAI_API_KEY 会启用可选的图片理解接口 /api/3d/analyze。配置后，上传图片会先被视觉模型识别为资产类型、材质重点、检查重点、展示场景、标签，并生成更适合 image-to-3D 的提示词。没配置时，应用继续使用本地文件名和元数据规则，不会影响基础上传和生成。
如需启用 Hunyuan3D 本地备用模式，先启动你的 Hunyuan3D API 服务，再设置：
HUNYUAN_API_BASE=http://127.0.0.1:8081
HUNYUAN_CREATE_PATH=/send
HUNYUAN_STATUS_PATH=/status
3D 生成后端支持这些路径：
Hyper3D 只走 Hyper3D Rodin 云端生成，默认模式
Tripo 只走 Tripo 云端生成
Fal 只走 Fal.ai 队列生成，具体模型在 Settings 里选择
Auto 先 Hyper3D，再 Tripo、Fal、Hunyuan，最后 JS Depth 兜底
Hunyuan 只走本地 Hunyuan3D
上传面板支持这些模式：
Hyper3D Hyper3D Rodin GLB 生成
Tripo Tripo 云端 GLB 生成
Fal Fal.ai 队列 GLB 生成
Hunyuan 本地 Hunyuan3D GLB 生成
JS Depth 浏览器侧图片深度浮雕，WebGL 不可用时降级到透明 PNG 分层
Auto Hyper3D -> Tripo -> Fal -> Hunyuan -> JS Depth 依次降级
Local GLB 导入已有 .glb 或自包含 .gltf
Tripo 上传使用当前 STS 对象存储流程，然后创建 image_to_model 任务。生成后的 GLB 会被 Node 后端缓存到 .generated-models/，后续展示优先使用本地副本。
Fal 上传使用官方 @fal-ai/client 的 storage 和 queue API。当前支持 Hunyuan3D v2、TRELLIS、TripoSR、Tripo3D v2.5 和 Hyper3D Rodin，具体 Fal 模型在 Settings 里选择。
Rodin 上传使用 Hyper3D 的 multipart /rodin 任务接口，然后轮询 /status 并通过 /download 下载和缓存 GLB。
前端模型库会保存到 IndexedDB，所以生成或导入成功的模型记录刷新后仍会恢复。
也可以从 New Upload 入口导入本地 .glb 或自包含 .gltf，导入后会成为自定义工作区模型。
Hunyuan3D 本地 API 预期形式：
POST /send
GET /status/:uid
状态接口可以返回远程模型 URL，也可以返回 model_base64 / glb_base64 这类 base64 GLB 字段。base64 GLB 会被缓存到 .generated-models/ 并由 Node 后端提供访问。
启动后端：
npm run dev:api
启动前端：
npm run dev
默认情况下，前端会访问本地 Node 后端 http://127.0.0.1:8787。
Demo 模型
仓库内置了一些缓存 GLB：
public/generated-models/
这些模型可以让项目在不消耗 API credits 的情况下直接用于演示。
参考模型
Library 面板内置了远程 Khronos glTF Sample Models 作为辅助参考，用于检查材质和 GLB 加载：
- Transmission Test，CC0，Adobe via Khronos。
- Transmission Roughness Test，CC-BY 4.0，Ed Mackey / Analytical Graphics via Khronos。
- Mosquito In Amber，CC-BY 4.0，Loic Norgeot / Geoffrey Marchal / Sketchfab via Khronos。
这些模型从 Khronos 已归档样例仓库远程加载，不打包进本仓库。
安全
不要把真实 API Key 写进前端代码。密钥只放在 .env.local，该文件已被 git 忽略。
License
MIT