---
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.

[![Run on Vercel](https://img.shields.io/badge/Run%20on-Vercel-000000?style=for-the-badge&logo=vercel)](https://img2three.vercel.app)
[![Open Hugging%20Face Space](https://img.shields.io/badge/Open-Hugging%20Face%20Space-FFD21E?style=for-the-badge&logo=huggingface&logoColor=000000)](https://huggingface.co/spaces/Yosun/img2three)

**Source:** [github.com/ai3d-dev/img2three](https://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

```bash
npm ci
npm run dev
```

Open the local Vite URL. No `.env` file or provider configuration is required. Build a production bundle with:

```bash
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.

```bash
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`.

```bash
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](LICENSE).

## 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.