| --- |
| 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. |
|
|
| [](https://img2three.vercel.app) |
| [](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. |
|
|
