3DCellForge

在生物学研究与教育中，传统的二维显微镜图像往往难以直观展示细胞复杂的三维空间结构。3DCellForge 是一个基于 React + Three.js 构建的原型平台，旨在通过 AI 技术将静态的细胞图像转化为高质感的交互式 3D 模型。

它不仅是一个查看器，更是一个完整的生成与探索工作台。通过集成 Tripo（云端）和 Hunyuan3D（本地）等前沿 Image-to-3D 模型，3DCellForge 能够自动从显微镜照片中重建细胞器的三维形态，并支持 WebGL 环境下的拖拽旋转、缩放、PBR 材质渲染及 GLB 导出，为科研演示、教学科普及数字艺术创作提供了全新视角。

核心亮点：智能生成、交互沉浸、灵活部署

1. AI 驱动的图片转 3D (Image-to-3D)

• 多引擎支持：
  • Tripo API：云端高性能生成，适合快速获取高质量模型。
  • Hunyuan3D：本地部署备用方案，保护数据隐私，降低长期成本。
  • JS Depth：浏览器端轻量级深度浮雕生成，作为无后端时的降级方案。
• 智能降级策略：提供 Auto 模式，依次尝试 Tripo → Hunyuan → JS Depth，确保在任何网络或硬件环境下都能获得可用的 3D 结果。
• 本地缓存机制：生成的 GLB 模型自动缓存至本地 .generated-models/ 目录，避免重复消耗 API Credits，加速后续加载。

2. 沉浸式交互式查看器

• 基于 React Three Fiber (R3F)：利用现代 Web 图形技术，实现流畅的 60fps 渲染。
• 专业交互控制：支持鼠标拖拽旋转、滚轮缩放、平移，以及“3D Proof”模式切换，满足专业审视需求。
• PBR 材质渲染：内置 Khronos glTF 参考模型，支持物理基于渲染（PBR）材质检查，确保光照、反射与透射效果的真实性。

3. 丰富的生物学上下文

• 细胞器详情卡：点击模型即可查看对应细胞器的生物学笔记、功能描述及显微镜参考图。
• 对比面板与图库：支持原始 2D 图像与生成 3D 模型的并列对比，方便验证重建准确性。
• 自定义细胞类型：允许用户导入本地 .glb 或自包含 .gltf 模型，扩展自身的细胞库。

4. 安全与隐私优先

• 密钥隔离：API Key 仅存储在服务端 `.env.local文件中，绝不暴露于前端代码包，防止密钥泄露。
• 本地化选项：支持完全本地化的 Hunyuan3D 部署，适合处理敏感科研数据。

快速开始

1. 安装依赖

npm install

2. 配置环境变量（可选）

若需使用云端生成或本地 Hunyuan3D，请复制配置文件并填写密钥：

cp .env.example .env.local

编辑 .env.local：

# Tripo 云端 API Key
TRIPO_API_KEY=your_tripo_key

# Hunyuan3D 本地服务地址（如需启用）
HUNYUAN_API_BASE=http://127.0.0.1:8081
HUNYUAN_CREATE_PATH=/send
HUNYUAN_STATUS_PATH=/status

3. 启动服务

启动后端（Node.js）：

npm run dev:api
# 默认运行在 http://127.0.0.1:8787

启动前端（Vite）：

npm run dev
# 打开终端显示的本地地址即可访问

4. 体验 Demo

仓库内置了缓存的 GLB 模型（位于 public/generated-models/），即使不配置 API Key，也可直接加载演示模型，体验交互式查看、截图及导出功能。

适用场景

技术架构详解

• 前端：React + Vite + Three.js + React Three Fiber + Drei + Framer Motion。
• 后端：Node.js Express，负责 API 密钥代理、文件缓存管理及任务状态轮询。
• AI 引擎：
  • Tripo：通过 STS 对象存储上传图像，调用 image_to_model 接口。
  • Hunyuan3D：通过 POST /send 提交任务，GET /status/:uid 获取结果（支持 URL 或 Base64 GLB）。
• 降级逻辑：
  • Tripo：仅云端。
  • Hunyuan：仅本地。
  • Auto：云端优先，失败转本地，再失败转前端 JS 深度计算。
  • Local GLB：直接加载用户自有模型。

3DCellForge 展示了 AI 与 Web 图形技术结合的巨大潜力。它降低了 3D 生物建模的门槛，让每一位研究者、教育者甚至爱好者都能轻松创建和探索微观世界的三维之美。

无论是用于严肃的科学研究，还是生动的课堂演示，3DCellForge 都提供了一个强大且灵活的解决方案。现在，克隆仓库，开启你的 3D 细胞探索之旅吧！