✨ What This Repo Contains

This repository is a public-ready demo project built on top of Tencent ARC's Pixal3D codebase.

• A Docker Compose setup for Windows/WSL2/Linux hosts with NVIDIA GPUs.
• Shared host caches for Hugging Face, Torch, and XDG data so large model files survive container rebuilds.
• Eight generated GLB game assets arranged in outputs/generated_game_assets/gallery.html.
• Non-destructive tilt-corrected GLB variants used by the viewer.
• A static Three.js viewer served locally on port 8787.
• Local compatibility patches used to run Pixal3D in this environment.

The upstream Pixal3D research code, citation, and license are preserved. This repo adds a solarpunk town demo and operational Docker packaging around it.

🏙️ Demo Assets

The town currently includes:

The viewer uses *_tilt_corrected.glb variants. The original GLB files are kept next to them for comparison and rollback.

Open outputs/generated_game_assets/gallery.html through the viewer service to orbit the scene, switch focus targets, and inspect the final layout.

🌍 Blender 360 Town World

The generated assets can also be arranged into a Blender 5.1.1 world:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\generate-solarpunk-town-world.ps1 -Blender "$env:LOCALAPPDATA\Microsoft\WindowsApps\blender-launcher.exe"

This creates:

outputs/generated_game_assets/workfiles/solarpunk_town_360.blend

The scene uses the panorama image as a 360-degree backdrop, places the models/tilt_corrected GLB facilities at varied scales, omits the unwanted turret asset, and uses a large central solar-tree facility as the town centerpiece.

Ground material assets:

outputs/generated_game_assets/images/textures/solarpunk_ground_texture.png
outputs/generated_game_assets/images/textures/solarpunk_ground_normal.png

The albedo texture is loaded as sRGB. The normal map is loaded as Non-Color and connected through a Blender Normal Map node.

Blender notes:

• Microsoft Store Blender may be installed under C:\Program Files\WindowsApps\..., where direct blender.exe execution can fail with Access is denied. Use the Windows app execution alias blender-launcher.exe.
• GLB imports often contain EMPTY helper nodes. The generator bakes transforms into the mesh objects and removes helper nodes so viewport axes/relationship lines do not clutter the scene.
• Avoid adding extra low-poly placeholder props unless they are explicitly requested; keep the world based on the generated Pixal3D facility models.

🚀 Quick Start

1. Prerequisites

• Windows + WSL2 + Docker Desktop, or Linux with Docker Engine.
• NVIDIA GPU with the NVIDIA Container Toolkit available to Docker.
• Enough disk space for CUDA/PyTorch/Pixal3D/TRELLIS model caches.
• Hugging Face access for gated background-removal models when PIXAL3D_SKIP_REMBG=0.

2. Build the Pixal3D image

docker compose build pixal3d

The image is large. It installs CUDA-enabled PyTorch, TRELLIS.2, Pixal3D dependencies, CUDA extensions, utils3d, and the NATTEN wheel used by this setup.

3. Serve the finished town viewer

docker compose up viewer

Then open:

http://127.0.0.1:8787/gallery.html

4. Convert an image into GLB

$env:PIXAL3D_INPUT='outputs/generated_game_assets/images/sources/solar_tree.png'
$env:PIXAL3D_OUTPUT='outputs/generated_game_assets/models/original/solar_tree.glb'
$env:PIXAL3D_FOV='0.2'
docker compose run --rm pixal3d

For already-isolated RGBA images, you can skip background removal:

$env:PIXAL3D_SKIP_REMBG='1'
docker compose run --rm pixal3d
Remove-Item Env:PIXAL3D_SKIP_REMBG

5. Run the Gradio app

docker compose --profile app up app

Then open:

http://127.0.0.1:7860

🧠 Shared Model Cache

The Compose file mounts these host directories into the container:

.cache/huggingface -> /workspace/.cache/huggingface
.cache/torch       -> /workspace/.cache/torch
.cache/xdg         -> /workspace/.cache/xdg

These directories are intentionally ignored by Git. They let you rebuild containers or run sibling containers without downloading large models again.

📁 Repository Layout

assets/generated_game_assets/     Source images for the first generated props
outputs/generated_game_assets/    Organized viewer, model, image, and report assets
docker/Dockerfile                 CUDA/PyTorch/Pixal3D build image
docker-compose.yml                Inference, Gradio app, and static viewer services
docker/README.md                  Docker-specific notes
pixal3d/                          Pixal3D library code
inference.py                      CLI image-to-GLB entrypoint
app.py                            Gradio app entrypoint

⚠️ Publishing Notes

The current Git remote may still point at the upstream Pixal3D repository. Before pushing publicly, create a new repository and set it as origin:

git remote remove origin
git remote add origin https://github.com/<your-user>/<your-repo>.git
git push -u origin master

Do not commit .cache/; it may contain large model files and local Hugging Face credentials.

📄 Attribution

This project is based on:

• TencentARC/Pixal3D
• microsoft/TRELLIS.2

If you use the Pixal3D research code, cite the original paper:

@article{li2026pixal3d,
    title={Pixal3D: Pixel-Aligned 3D Generation from Images},
    author={Li, Dong-Yang and Zhao, Wang and Chen, Yuxin and Hu, Wenbo and Guo, Meng-Hao and Zhang, Fang-Lue and Shan, Ying and Hu, Shi-Min},
    journal={arXiv preprint arXiv:2605.10922},
    year={2026}
}