From bef6e592e094f05a25c1718d2d03c5edacff8e2a Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:20:48 +0000 Subject: [PATCH] docs: make Chinese README the default --- README.md | 166 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 86 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 4e43285..6c00e00 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,42 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/huangserva/3DCellForge) · [上游 README](https://github.com/huangserva/3DCellForge/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + # 3D Model Studio [English](README.md) | [中文](README.zh-CN.md) -AI-powered interactive 3D model generation, inspection, and presentation studio. +AI 驱动的交互式 3D 模型生成、检查和演示工作台。 -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. +3D Model Studio 是一个 React + Three.js 原型，用于把上传图片或 GLB 文件变成可交互的 3D 模型工作区。它支持 WebGL 拖拽旋转、滚轮缩放、左侧模型库 / 中央 3D 舞台 / 右侧工具区、截图、GLB 导出、历史上传默认收起、Demo 演示模式、生成队列，以及通过 Hyper3D / Tripo / Fal.ai / Hunyuan3D / JS Depth / 本地模型导入生成或加载 3D 模型。 -## Demo +## 演示视频 -[![3D Model Studio demo](docs/demo/3DCellForge-demo-cover.jpg)](docs/demo/3DCellForge-demo-2026-05-10.mp4) +[![3D Model Studio 演示视频](docs/demo/3DCellForge-demo-cover.jpg)](docs/demo/3DCellForge-demo-2026-05-10.mp4) -Open the demo video: [Demo MP4](docs/demo/3DCellForge-demo-2026-05-10.mp4) +打开视频文件：[演示 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. +- 基于 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`，不会暴露到前端包里。 -## Tech Stack +## 技术栈 - React - Vite @@ -37,34 +44,34 @@ Open the demo video: [Demo MP4](docs/demo/3DCellForge-demo-2026-05-10.mp4) - React Three Fiber - Drei - Framer Motion -- Tripo API optional backend -- Fal.ai optional backend -- Hunyuan3D local API optional backend +- Tripo API 可选后端 +- Fal.ai 可选后端 +- Hunyuan3D 本地 API 可选后端 -## Quick Start +## 快速开始 ```bash npm install npm run dev ``` -Open the Vite URL shown in the terminal. +打开终端里显示的 Vite 地址即可。 -## 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. +- 左侧 `Model Library` 固定展示当前激活的生成 / 导入资产。 +- 更早生成、导入过的模型会收进 `Saved Assets`，默认折叠。 +- 右侧 `Asset Source` 用来选择生成模式或导入本地 `.glb` / `.gltf`。 +- 左侧 `Generation Queue` 可以查看上传、生成、导入状态，并对失败任务重试。 +- 需要部件说明时，再点击 `Info` 或 `Inspect` 打开详情抽屉。 +- 顶部打开 `Library` 可以查看完整资产库：预览、Provider 状态、任务 ID、GLB URL 复制、Provider 对比和删除。 +- 顶部点击 `Demo` 进入纯展示模式，适合截图、录屏、演示。 +- 录屏前先看主舞台的质量评分；分数低通常说明源图或生成结果还不适合演示。 +- Demo 动画会根据模型名称和元数据切换：汽车走低机位推进，飞机走飞行掠过，航母 / 船走侧向巡航，有机 / 标本类资产走工作室环绕。 -Useful validation commands: +常用验证命令： ```bash npm run lint @@ -73,17 +80,17 @@ 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. +`npm run test:visual` 会运行 Playwright 布局和截图回归，覆盖工作台、Model Library 抽屉和 Demo Mode。只有确认 UI 改动是预期变化时，才运行 `npm run test:visual:update` 更新截图基线。 -## Optional Image-to-3D Backend +## 可选 Image-to-3D 后端 -To enable image-to-3D generation, create `.env.local`: +创建 `.env.local`： ```bash cp .env.example .env.local ``` -Then set: +然后设置： ```bash TRIPO_API_KEY=your_tripo_key @@ -93,9 +100,9 @@ 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. +`OPENAI_API_KEY` 会启用可选的图片理解接口 `/api/3d/analyze`。配置后，上传图片会先被视觉模型识别为资产类型、材质重点、检查重点、展示场景、标签，并生成更适合 image-to-3D 的提示词。没配置时，应用继续使用本地文件名和元数据规则，不会影响基础上传和生成。 -For Hunyuan3D local backup mode, start your local Hunyuan3D API server and set: +如需启用 Hunyuan3D 本地备用模式，先启动你的 Hunyuan3D API 服务，再设置： ```bash HUNYUAN_API_BASE=http://127.0.0.1:8081 @@ -103,82 +110,81 @@ HUNYUAN_CREATE_PATH=/send HUNYUAN_STATUS_PATH=/status ``` -The 3D generation backend supports these provider paths: +3D 生成后端支持这些路径： ```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 +Hyper3D 只走 Hyper3D Rodin 云端生成，默认模式 +Tripo 只走 Tripo 云端生成 +Fal 只走 Fal.ai 队列生成，具体模型在 Settings 里选择 +Auto 先 Hyper3D，再 Tripo、Fal、Hunyuan，最后 JS Depth 兜底 +Hunyuan 只走本地 Hunyuan3D ``` -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 +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 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. +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，所以生成或导入成功的模型记录刷新后仍会恢复。 -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. +也可以从 `New Upload` 入口导入本地 `.glb` 或自包含 `.gltf`，导入后会成为自定义工作区模型。 -Expected Hunyuan3D local API shape: +Hunyuan3D 本地 API 预期形式： ```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. +状态接口可以返回远程模型 URL，也可以返回 `model_base64` / `glb_base64` 这类 base64 GLB 字段。base64 GLB 会被缓存到 `.generated-models/` 并由 Node 后端提供访问。 -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. +默认情况下，前端会访问本地 Node 后端 `http://127.0.0.1:8787`。 -## Demo Models +## Demo 模型 -The repository includes cached generated GLB files under: +仓库内置了一些缓存 GLB： ```text public/generated-models/ ``` -These make the demo usable without spending API credits on every run. +这些模型可以让项目在不消耗 API credits 的情况下直接用于演示。 -## Reference Models +## 参考模型 -The Library panel includes remote Khronos glTF Sample Models as auxiliary references for material and loader checks: +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. +- 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. +这些模型从 Khronos 已归档样例仓库远程加载，不打包进本仓库。 -## Security +## 安全 -Do not put real API keys in frontend code. Keep secrets in `.env.local`, which is ignored by git. +不要把真实 API Key 写进前端代码。密钥只放在 `.env.local`，该文件已被 git 忽略。 ## License