3DCellForge: a React and Three.js workbench for image-to-3D generation

The gap 3DCellForge fills between an API and a finished model

Image-to-3D services return a file. What you do with that file is usually the harder part: viewing it, judging whether it is good enough to show, comparing it against earlier attempts, and exporting something a colleague can open. 3DCellForge is a React + Three.js prototype aimed at that second half. The README describes it as a studio for "AI-powered interactive 3D model generation, inspection, and presentation", and the repository layout backs that up: a Vite frontend under src/, a Node backend in server.mjs and server/, and Playwright configuration at the top level.

The intended user is someone who already has, or is willing to get, an account with one of the supported providers: Hyper3D Rodin, Tripo, Fal.ai, or a locally hosted Hunyuan3D instance. It is not a tool for people who want to type a prompt and receive a model with no configuration. The default screen is described in the README as "intentionally quiet", with a Model Library rail on the left, a WebGL stage in the centre, and an Asset Source rail on the right. That layout tells you what the project thinks the work is: pick an asset, look at it, decide whether to keep it.

How the provider abstraction and the local GLB cache actually work

The mechanism worth understanding is the split between the browser and the Node backend. The frontend never holds an API key. The README states plainly that the key "stays server-side in .env.local; it is never exposed to the frontend bundle", and the frontend talks to the local backend at http://127.0.0.1:8787 by default. That is a sensible boundary for a prototype that talks to paid APIs.

Each provider path has its own upload and polling shape. Tripo uploads go through an STS object-storage flow at /upload/sts/token before an image_to_model task is created. Rodin uploads use Hyper3D's multipart /rodin task API, then poll /status and cache the GLB returned by /download. Fal uploads use the official @fal-ai/client storage and queue APIs. Hunyuan3D is the odd one out: it expects a local server exposing POST /send and GET /status/:uid, and the status response may return either a remote model URL or a base64 GLB field such as model_base64 or glb_base64.

Generated GLBs are cached by the Node backend under .generated-models/, so a second view uses the local copy instead of a temporary provider URL. The frontend asset library lives in IndexedDB, with localStorage as a compact fallback, so generated and imported records survive a refresh. The Auto mode is a fallback chain rather than a load balancer: Hyper3D first, then Tripo, Fal, Hunyuan, and JS Depth. JS Depth is described as browser-side image relief with a layered PNG fallback, which is a different kind of output from a real mesh. Treat Auto as convenient, not as equivalent quality across the chain.

Installing 3DCellForge and running a first generation

The quick start in the README is two commands. It assumes Node and npm are already available, and the package.json pins React 19, Three.js 0.184, Vite 8 and React Three Fiber 9.

npm install
npm run dev

Open the Vite URL printed in the terminal. At this point the viewer and the import path work, but image-to-3D generation does not, because no provider key is configured. To enable it, copy the example environment file and fill in the keys you actually have:

cp .env.example .env.local

The example file lists TRIPO_API_KEY, RODIN_API_KEY, FAL_API_KEY and OPENAI_API_KEY, along with API_HOST and API_PORT (8787 by default). OPENAI_API_KEY is optional and only enables image understanding through /api/3d/analyze; without it the README says the app falls back to local filename and metadata heuristics. Then start the backend in a second terminal:

npm run dev:api

With the backend running, choose a provider in the right-hand Asset Source rail and upload a reference image. Watch the Generation Queue panel on the left for upload, generation and import state. When a GLB comes back, check the quality card on the stage before recording anything; the README warns that low scores usually mean the source image or the provider result is not demo-ready. If you only want to look at an existing file, use the New Upload button to import a .glb or a self-contained .gltf, which becomes a custom workspace model served from the same local cache.

Where 3DCellForge will let you down

The most concrete limitation is that there is no published release. The repository has no retrieved releases, and package.json still carries version 0.1.0. The README calls the project a prototype. There is no upgrade path documented, no changelog, and no migration notes, so if you build on top of it you are tracking the main branch.

Provider dependence is the second constraint. Every real mesh path except local Hunyuan3D and Local GLB import requires an external account and a key. The README does not document rate limits, quotas, or what happens when a provider returns an error mid-queue. The generation queue is described as compact, not as durable: there is no statement about resuming a failed task after a restart.

The third issue is scope. The inspector infers category, material focus and tags, and the demo camera adapts to the model name and metadata (cars get a road push-in, aircraft a flight pass, ships a naval cruise, organic specimens a studio orbit). That inference is heuristic. For anything outside the listed categories, the presentation layer adds little, and you are better served by a plain GLB viewer. The JS Depth mode is also easy to misread: it produces a layered image relief, not a textured mesh, so it is not a substitute for a provider result when you need geometry.

How 3DCellForge differs from calling Tripo or Fal directly

The obvious alternative is to call the provider API yourself and open the resulting GLB in a generic viewer such as the Khronos glTF sample viewer or any Three.js scene. That path gives you full control over retries, storage and naming, and it has no frontend to maintain. What you lose is everything 3DCellForge assembles around the call: the three-column workbench, the comparison panel, the object-aware inspector, the quality score covering file size, triangle count and texture count, and Demo Mode, which hides the side panels and runs a cinematic camera path for screenshots and recordings.

The second alternative is a hosted product from one of the providers. That removes the setup entirely, but it also removes the local cache under .generated-models/ and the IndexedDB library, and it puts your reference images on someone else's infrastructure. 3DCellForge keeps the browser talking only to 127.0.0.1:8787. If your constraint is data locality, that difference matters more than any feature comparison. If your constraint is time to first model, the hosted route wins.

Maintenance cost, the licence, and what the test suite covers

3DCellForge is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is the whole of the licence implication; the repository does not add a separate terms file, and nothing in the README speaks to the licences of the provider APIs you connect to, which you should check separately.

The last push to the default branch was on 2026-08-27, so the project is recent rather than dormant. There are still no tagged releases, so expect to read commits rather than release notes when something changes. The dependency set is broad for a prototype: React 19, Three.js, React Three Fiber, Drei, postprocessing, Framer Motion, lucide-react, undici and the Fal client. Each of those moves independently, and the Vite 8 and ESLint 10 versions are recent majors.

The repository does ship validation commands, which is more than many prototypes at this stage. npm run lint, npm run build and npm run test (node --test over test/*.test.mjs) cover static checks, the production build and unit tests. npm run test:visual runs Playwright layout and screenshot regression checks for the workbench, the Model Library drawer and Demo Mode; the README says to use npm run test:visual:update only when an intentional UI change needs new screenshot baselines. That last command is the one to be careful with, because regenerating baselines will hide a real layout regression if you run it reflexively.

Editorial conclusion

Adopt 3DCellForge if you want a local workbench that keeps provider keys server-side and gives you a repeatable demo mode with Playwright screenshot checks. Do not adopt it if you need a documented, versioned release, a hosted service, or a generation pipeline that works without a third-party account. Before committing, verify that npm run test:visual passes on your machine and that your chosen provider key is accepted by the backend you start with npm run dev:api.

Frequently asked questions

Official sources

1. huangserva/3DCellForge on GitHub
2. Issues
3. License: MIT
4. README