Supra-3D/PhysAg3D

What it does

PhysAg3D takes one image and produces a textured 3D asset whose visible parts can actually move. A vision-language agent proposes semantic parts, interactions, and physical priors; a pretrained 3D generator (TRELLIS.2) produces the object mesh from the same image. The agent then builds joints and compliant regions, binds them to the generated surfaces, and refines the result using rendered observations and execution measurements within a fixed budget. Rigid articulated parts and deformable regions are both supported.

Delivered cases keep the source image, native candidate, authoring files, interaction evidence, and a delivery report together, so the result can be inspected rather than just viewed. This is a research workflow, not a hosted service: the repository ships the agent-assisted preparation and execution tools, while the generation host and model weights must already exist.

Quick start

The released configuration uses a Windows controller driving a Linux GPU host over SSH. Prepare the controller in PowerShell:

git clone --branch main --single-branch https://github.com/Supra-3D/PhysAg3D.git
cd PhysAg3D
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.observed.txt
Copy-Item examples/runtime.windows-ssh.json config/runtime.local.json

Edit config/runtime.local.json: point python, blender, and codex at installed executables, set trellis.ssh_host to an SSH alias with non-interactive login and a known host key, and set the TRELLIS.2, runtime, model, DINOv3, BiRefNet, and jobs_root paths to writable absolute Linux paths. Keep resolution 1024, steps 24, texture size 2048, and seed 42.

Then verify and run a case:

.\.venv\Scripts\python.exe execute.py verify
.\.venv\Scripts\python.exe execute.py doctor --config config/runtime.local.json --native
.\.venv\Scripts\python.exe execute.py prepare --image inputs/fig8_01_4fe3cc6a.png --config config/runtime.local.json --out ../PhysAg3D-runs/example-01
.\.venv\Scripts\python.exe execute.py plan ../PhysAg3D-runs/example-01
.\.venv\Scripts\python.exe execute.py run ../PhysAg3D-runs/example-01

prepare copies inputs and assigns a native job root without calling a model; run starts the agent worker and can submit GPU jobs. The result is summarized in the case's delivery.json, with a refined GLB, editable Blender file, MuJoCo scene, motion video, and comparisons. If a viewer exists at presentation/index.html, serve the case directory with python -m http.server 8000 --bind 127.0.0.1 --directory ../PhysAg3D-runs/example-01 and open the presentation page. An experimental Linux-local profile is also provided.

Requirements and limits

The controller needs Python 3.11+, Blender (the recorded workflow uses 5.2.1), a Codex CLI with your own ChatGPT login, and SSH. The launcher requires gpt-6-astra at high reasoning effort and checks CLI flags. The generation host needs a Linux NVIDIA GPU with TRELLIS.2, DINOv3, and BiRefNet deployed; the example profile requires at least 28 GiB of free GPU memory before submission. Model weights and the generation host are not bundled, and requirements.observed.txt is an observed-version record rather than a clean-install lock.

The default case budget is three hours with at most two acceptance passes and two repair rounds. The launcher rejects changes to prepared inputs or configuration and does not silently resume an attempted case. Agent outputs are not fully isolated: declared historical code-only references may be adapted, and results depend on model access, external runtime versions, and per-case decisions. Worker completion alone does not mean the interaction and physics checks passed; check interaction_status, physics_status, motion_kind, and limitations. A single image leaves hidden structure, scale, and material parameters uncertain, and these are recorded as estimates. Original source code is MIT-licensed; bundled Three.js and external tools or weights keep their own licenses.

HotRepo's take

PhysAg3D entered HotRepo's new-project ranking on 1 November 2026, when it was recorded with 106 stars and 6 stars gained over a roughly two-hour observation window. That single snapshot shows early attention for the single-image interactive-asset workflow, but it does not establish a trend, adoption, or physical-accuracy claims. The more practical signal for readers is the release format itself: a two-machine agent workflow with explicit environment checks, hashes, and per-case delivery reports, which makes the tool inspectable but also sets a high bar for running it outside a suitably equipped lab.

Project source and documentation