docs: preserve upstream English README
This commit is contained in:
wehub-resource-sync
+185
@@ -0,0 +1,185 @@
|
||||
# 3D Model Studio
|
||||
|
||||
[English](README.md) | [中文](README.zh-CN.md)
|
||||
|
||||
AI-powered interactive 3D model generation, inspection, and presentation studio.
|
||||
|
||||
3D Model Studio is a React + Three.js prototype for turning uploaded reference images or GLB files into a polished interactive 3D workspace. It supports live WebGL orbit controls, a left model library / center stage / right tools workbench, screenshots, GLB export, collapsed upload history, demo presentation mode, a generation queue, and optional image-to-3D providers for generating real 3D models from uploaded reference images.
|
||||
|
||||
## Demo
|
||||
|
||||
[](docs/demo/3DCellForge-demo-2026-05-10.mp4)
|
||||
|
||||
Open the demo video: [Demo MP4](docs/demo/3DCellForge-demo-2026-05-10.mp4)
|
||||
|
||||
## Features
|
||||
|
||||
- Interactive model viewer built with React Three Fiber.
|
||||
- Three-column workbench: Model Library on the left, WebGL stage in the center, asset/generation tools on the right.
|
||||
- Drag to rotate, scroll to zoom, isolate structure parts, inspect model details, and export the current scene.
|
||||
- Object-aware inspector with inferred category, source, provider state, material focus, demo value, and tags for vehicles, aircraft, vessels, products, artifacts, and organic specimens.
|
||||
- Model quality score for generated GLBs, including file size, triangle count, texture count, and demo readiness.
|
||||
- Demo Mode for screenshots and screen recordings: hides side panels, uses object-aware cinematic camera paths, and shows a clean presentation overlay.
|
||||
- Productized Model Library drawer with source thumbnails, provider/status, task id, GLB URL actions, comparison, and delete controls.
|
||||
- Saved Assets stays collapsed by default, while the active generated/imported asset stays pinned and clickable.
|
||||
- Generated/imported models are restored after refresh through IndexedDB, with localStorage as a compact fallback.
|
||||
- Generic part detail drawer, asset references, comparison panel, notes, gallery actions, logs, saved projects, and a compact generation queue.
|
||||
- Hyper3D, Tripo, Fal.ai, Hunyuan3D, JS Depth, and Local GLB generation/import modes.
|
||||
- Cached demo GLB models for offline-friendly screenshots and demos.
|
||||
- Auxiliary Khronos glTF reference models for GLB loader and PBR material checks.
|
||||
- API key stays server-side in `.env.local`; it is never exposed to the frontend bundle.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- React
|
||||
- Vite
|
||||
- Three.js
|
||||
- React Three Fiber
|
||||
- Drei
|
||||
- Framer Motion
|
||||
- Tripo API optional backend
|
||||
- Fal.ai optional backend
|
||||
- Hunyuan3D local API optional backend
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open the Vite URL shown in the terminal.
|
||||
|
||||
## Workbench Workflow
|
||||
|
||||
The default screen is intentionally quiet:
|
||||
|
||||
- Pick the active generated/imported asset from the left `Model Library` rail.
|
||||
- Earlier generated/imported models are tucked under `Saved Assets` until expanded.
|
||||
- Use the right `Asset Source` rail to choose the generation provider or import a local `.glb` / `.gltf`.
|
||||
- Watch upload/generation/import state in the left `Generation Queue` panel.
|
||||
- Click `Info` or `Inspect` only when you need the part detail drawer.
|
||||
- Open top-nav `Library` for the full asset catalog with previews, provider state, task ids, GLB URL copy, provider comparison, and deletion.
|
||||
- Click `Demo` in the top navigation to enter a clean presentation mode for screenshots and recordings.
|
||||
- Check the quality card on the stage before recording; low scores usually mean the source image or provider result is not demo-ready.
|
||||
- Demo animation adapts to the model name and metadata: cars use a road push-in, aircraft use a flight pass, ships/carriers use a naval cruise, and organic/specimen assets use a studio orbit.
|
||||
|
||||
Useful validation commands:
|
||||
|
||||
```bash
|
||||
npm run lint
|
||||
npm run build
|
||||
npm run test
|
||||
npm run test:visual
|
||||
```
|
||||
|
||||
`npm run test:visual` runs Playwright layout and screenshot regression checks for the workbench, the Model Library drawer, and Demo Mode. Use `npm run test:visual:update` only when an intentional UI change needs new screenshot baselines.
|
||||
|
||||
## Optional Image-to-3D Backend
|
||||
|
||||
To enable image-to-3D generation, create `.env.local`:
|
||||
|
||||
```bash
|
||||
cp .env.example .env.local
|
||||
```
|
||||
|
||||
Then set:
|
||||
|
||||
```bash
|
||||
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` enables optional image understanding through `/api/3d/analyze`. When configured, uploads are classified by vision into asset type, material focus, inspection notes, scene profile, tags, and a better image-to-3D prompt. Without it, the app keeps using local filename/metadata heuristics.
|
||||
|
||||
For Hunyuan3D local backup mode, start your local Hunyuan3D API server and set:
|
||||
|
||||
```bash
|
||||
HUNYUAN_API_BASE=http://127.0.0.1:8081
|
||||
HUNYUAN_CREATE_PATH=/send
|
||||
HUNYUAN_STATUS_PATH=/status
|
||||
```
|
||||
|
||||
The 3D generation backend supports these provider paths:
|
||||
|
||||
```text
|
||||
Hyper3D Hyper3D Rodin cloud generation only (default)
|
||||
Tripo Tripo cloud generation only
|
||||
Fal Fal.ai queue generation; model is selected in Settings
|
||||
Auto Hyper3D first, then Tripo, Fal, Hunyuan, and JS Depth backup
|
||||
Hunyuan Local Hunyuan3D generation only
|
||||
```
|
||||
|
||||
The upload panel exposes the full generation mode choice before picking a file:
|
||||
|
||||
```text
|
||||
Hyper3D Hyper3D Rodin GLB generation
|
||||
Tripo Tripo cloud GLB generation
|
||||
Fal Fal.ai queue GLB generation
|
||||
Hunyuan Local Hunyuan3D GLB generation
|
||||
JS Depth Browser-side image relief with layered PNG fallback
|
||||
Auto Hyper3D, Tripo, Fal, Hunyuan, then JS Depth fallback
|
||||
Local GLB Import an existing .glb or self-contained .gltf
|
||||
```
|
||||
|
||||
Tripo uploads use the current STS object-storage flow (`/upload/sts/token`) before creating an `image_to_model` task.
|
||||
Fal uploads use the official `@fal-ai/client` storage and queue APIs. Supported Fal models are Hunyuan3D v2, TRELLIS, TripoSR, Tripo3D v2.5, and Hyper3D Rodin. Pick the active Fal model in `Settings`.
|
||||
Rodin uploads use Hyper3D's multipart `/rodin` task API, then poll `/status` and cache the GLB returned by `/download`.
|
||||
Generated GLBs are cached by the Node backend under `.generated-models/`, so later views use the local copy instead of temporary provider URLs.
|
||||
The frontend model library is saved in IndexedDB, so successful generated/imported model records survive page refreshes.
|
||||
|
||||
You can also import a local `.glb` or self-contained `.gltf` from the `New Upload` button. Imported models become custom workspace models and are served from the same local cache.
|
||||
|
||||
Expected Hunyuan3D local API shape:
|
||||
|
||||
```text
|
||||
POST /send
|
||||
GET /status/:uid
|
||||
```
|
||||
|
||||
The status response can return either a remote model URL or a base64 GLB field such as `model_base64` / `glb_base64`. Base64 GLBs are cached under `.generated-models/` and served by the Node backend.
|
||||
|
||||
Start the backend:
|
||||
|
||||
```bash
|
||||
npm run dev:api
|
||||
```
|
||||
|
||||
Then start the frontend:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The frontend talks to the local Node backend at `http://127.0.0.1:8787` by default.
|
||||
|
||||
## Demo Models
|
||||
|
||||
The repository includes cached generated GLB files under:
|
||||
|
||||
```text
|
||||
public/generated-models/
|
||||
```
|
||||
|
||||
These make the demo usable without spending API credits on every run.
|
||||
|
||||
## Reference Models
|
||||
|
||||
The Library panel includes remote Khronos glTF Sample Models as auxiliary references for material and loader checks:
|
||||
|
||||
- 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.
|
||||
|
||||
These are loaded from the archived Khronos sample repository and are not bundled into this repo.
|
||||
|
||||
## Security
|
||||
|
||||
Do not put real API keys in frontend code. Keep secrets in `.env.local`, which is ignored by git.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user