Asset3D Factory

A containerized image-to-3D pipeline for Stability AI's Stable-Fast-3D (SF3D) and Microsoft TRELLIS.2, with a Unity client for selecting a model, monitoring its status, and importing generated GLB assets.

🚀 Features

• FastAPI Backend: Asynchronous endpoints for 3D mesh generation.
• Automatic Background Removal: Integrated rembg processing.
• Unity Integration: Includes a multi-model manager and UI for polling service state and importing generated GLB files.
• GPU Optimized: Configured for CUDA-enabled environments.

🛠️ Repository Structure

• Dockerfile.sf3d: Build definition for the SF3D CUDA 12.4 environment.
• sf3d_server.py: The SF3D FastAPI application handling model inference and texture baking.
• models/sf3d/: SF3D source code and model-specific dependencies.
• models/trellis2/: Microsoft TRELLIS.2 source code and model-specific dependencies.
• trellis2_server.py: FastAPI service for TRELLIS.2 image-to-3D generation.
• Dockerfile.trellis2: CUDA 12.4 image definition for the TRELLIS.2 service.
• Asset3dFactory.Unity/Assets/Scripts/Generative3DModelManager.cs: Configurable Unity manager for model services and generation.
• Asset3dFactory.Unity/Assets/Scripts/Generative3DModelManagerUI.cs: Unity UI Toolkit controller for model selection, status, and generation reports.
• .gitignore: Standard Python/Docker exclusions.

📦 Setup & Installation

1. Requirements

• Docker Desktop with NVIDIA Container Toolkit installed.
• NVIDIA GPU (RTX 30-series or 40-series recommended).

2. Authentication

Create a .env file in the root directory and add your Hugging Face token to download the model weights:

HF_TOKEN=your_hugging_face_token_here

3. Build and Run

# Build the SF3D image
docker build -f Dockerfile.sf3d -t sf3d-server .

# Run the container with GPU access
docker run --gpus all -p 8000:8000 --env-file .env sf3d-server

# Build the TRELLIS.2 image
docker build -f Dockerfile.trellis2 -t trellis2-server .

# Run TRELLIS.2 on port 8001
docker run --gpus all -p 8001:8001 --env-file .env trellis2-server

🔌 API Usage

Endpoint: POST /generate
Input: Multipart Form-Data with a file field containing your image.
Output: A binary .glb file (model/gltf-binary).

Unity Module

The Unity client is an interactive front end for selecting an input image, choosing a generator, and inspecting the resulting GLB assets in the scene. The sample scene configures SF3D on port 8000 and TRELLIS.2 on port 8001.

Generation workflow

• Switch between configured generators and generate a model from the selected image.
• Add compatible endpoints through Generative3DModelManager's serialized service list.
• Monitor service readiness and inspect the selected model, generation duration, file size, and triangle count.

Viewing and comparison

• Rotate models with the new Input System, including optional synchronized auto-rotation during comparison.
• Browse saved generations with their metadata and source-image thumbnails.
• Reload a saved model in the center or compare it with the current model side by side.

Service Status API

Both containers expose the same status endpoints. The response format is identical for SF3D (http://localhost:8000) and TRELLIS.2 (http://localhost:8001), so a Unity client can poll either service using the same model.

• GET /health - liveness endpoint. Returns 200 while the API process is running, including when the model failed to load, with the full status payload.
• GET /ready - readiness endpoint. Returns 200 only after the model has loaded; returns 503 during loading or after a load failure.
• GET /status - full status payload for Unity polling. Always returns 200 while the API process is running.

Example /status response:

{
	"service": "trellis2",
	"state": "busy",
	"uptime_seconds": 18.42,
	"model": {
		"id": "microsoft/TRELLIS.2-4B",
		"state": "ready",
		"device": "cuda",
		"loaded_at": "2026-08-06T12:00:00+00:00",
		"error": null
	},
	"generation": {
		"state": "running",
		"active": 1,
		"completed": 4,
		"failed": 0,
		"last_started_at": "2026-08-06T12:00:10+00:00",
		"last_completed_at": "2026-08-06T11:58:23+00:00",
		"last_error": null
	}
}

Service state is starting, ready, busy, or error. Model state is starting, ready, or error; use model.error and generation.last_error for a user-facing diagnostic message. POST /generate returns 503 until the model is ready.

The TRELLIS.2 service uses the 512-resolution pipeline by default. Override it with TRELLIS_PIPELINE=1024_cascade only if the available GPU memory allows it.

---

Note: Ensure your Hugging Face account has accepted the license terms for Stable-Fast-3D before the first run.