title: img2three
emoji: 🧊
colorFrom: indigo
colorTo: green
sdk: static
pinned: false
img2three
A static, open-source image-to-procedural-Three.js demo. It turns a single reference image into a validated, editable scene—not a locked generated asset.
Source: github.com/ai3d-dev/img2three
Why this matters
Most image-to-3D demos produce an opaque file or a rendered preview. img2three produces a constrained Three.js scene specification that you can inspect, orbit, export, and edit. It makes the workflow accessible in a public browser app while keeping platform secrets out of the product: each visitor brings their own OpenAI key, which goes directly to OpenAI and is cleared after the run.
Origins and improvements
img2three was inspired by the original img2threejs experiment by hoainho. This project turns that idea into a deployable, privacy-conscious workflow with a browser UI, parallel model comparison, strict JSON-schema and Zod validation, safe declarative scene data rather than generated executable code, interactive previews, and direct Three.js export.
Privacy and API keys
img2three is intentionally bring your own key:
- The app has no backend, no hosted OpenAI key, and no alternate cloud-provider integration.
- Your key is held in memory only while a generation runs, then cleared.
- The browser sends the key directly to
https://api.openai.com; it is never saved in local storage, source code, build output, hosting configuration, or application logs. - Treat keys entered in any browser app as sensitive. Use a restricted, revocable project key and revoke it if you suspect exposure.
Local development
npm ci
npm run dev
Open the local Vite URL. No .env file or provider configuration is required. Build a production bundle with:
npm run build
npm run preview
Deploy to Vercel
vercel.json declares a static Vite deployment. Do not set OPENAI_API_KEY, VITE_OPENAI_API_KEY, AWS credentials, or any other provider secret in Vercel.
npm ci
npm run build
npx vercel --prod --name img2three
The resulting deployment is static: it never handles a visitor's OpenAI key.
Deploy to Hugging Face Spaces
The supplied Python SDK script creates/updates a Static Space and uploads only README.md and the generated dist/ files. It does not upload .env, deployment tokens, source secrets, or node_modules.
npm ci
npm run build
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-deploy.txt
hf auth login
python scripts/deploy_hf_space.py --repo-id your-user/img2three
The script uses your saved Hugging Face login by default; HF_TOKEN may be supplied by CI instead. Credentials are never written into the Space or static build.
Open-source hygiene
.env*, host metadata, private-key formats, build artifacts, and dependencies are ignored; .env.example is deliberately key-free. This project is licensed under MIT.
Notes
Output is a constrained data scene, not model-generated executable code. A single source image cannot reveal hidden surfaces, so generated geometry is a reconstruction rather than photogrammetric truth.