README.md

---
title: Particle Blueprint 3D
emoji: 🧊
colorFrom: indigo
colorTo: blue
sdk: gradio
app_file: app.py
python_version: "3.10"
startup_duration_timeout: 1h
preload_from_hub:
  - tencent/Hunyuan3D-1
  - Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled
  - tencent/Hunyuan3D-Omni
---

# Particle Blueprint 3D

Mobile-first 3D concept workflow for Hugging Face Spaces.

## What this build does

- takes a text prompt
- tries to run **Hunyuan3D-1** for prompt-to-3D generation
- converts the AI result into a **particle blueprint** for inspection
- lets the user review that blueprint on iPhone first
- exports the mesh as a **GLB** when approved
- preloads **Hunyuan3D-Omni** into the Space cache for the next stage of controllable refinement work

## Why this shape

This build is aimed at a scaffold-first workflow rather than a one-shot "magic GLB" workflow. The blueprint is treated as the inspection layer between prompt and final asset.

## Important note

This repo is rebuilt around the official Hugging Face-hosted Tencent model weights, but the second-stage **Hunyuan3D-Omni** refinement command is still marked experimental in this build. The current mesh export step returns the Hunyuan3D-1 AI mesh normalized to GLB while also caching Omni for future control-driven refinement.

## First-run expectations

The first run can take a while because the Space may need to:

1. cache the large model repos
2. clone the upstream Tencent code repos
3. run the heavier text-to-3D stack

If the Hunyuan path fails because the upstream repo still needs extra GPU-side dependencies in your runtime, the app falls back to the local scaffold builder so the UI still works.