ForMesh3D — Open-Source Generative 3D Studio & Production Pipeline

A unified, self-hosted 3D creation suite for neural 3D generation, asset finishing, and engine-ready delivery
Text-to-Motion • Image-to-3D • Quad Retopology • PBR Material Painting • Auto-Rigging • Automated LODs • Game Engine Ready

⚡ Quick Start: git clone --recurse-submodules https://github.com/Silentzx2/ForMesh3D.git → bash scripts/setup.sh → bash scripts/start.sh → Open http://localhost:3000

• 1. Overview & Core Mission
• 2. Core Capability Matrix
• 3. End-to-End Asset Generation Pipeline
• 4. System Architecture
• 5. Supported AI Model Catalog
• 6. GPU Doctor & Hardware Execution Planner
• 7. Studio Workspace & Interactive 3D Viewport
• 8. Production Post-Processing Engine
• 9. Technology Stack
• 10. Installation & Quick Start
• 11. REST & Streaming API Reference
• 12. Verification & Test Suite
• 13. Frequently Asked Questions (FAQ)
• 14. Technical Documentation Index
• 15. License & Legal Attribution

ForMesh3D is an open-source, self-hosted generative 3D asset creation and mesh-finishing platform. It bridges modern open research neural models into a single, cohesive studio running entirely on your local workstation or private GPU cluster.

Traditional AI 3D generators typically output dense, raw, untextured "triangle soups" that require hours of manual cleanup in external 3D software. ForMesh3D solves this by integrating neural generation directly with a complete production finishing pipeline:

• 100% Private & Self-Hosted: Run neural inference locally on NVIDIA GPUs without cloud subscriptions, usage queues, or uploading proprietary concept art to external services.
• Immutable Source Preservation: Raw model-native generation is snapshotted at master/source.glb with SHA-256 validation before any downstream production decimation or retopology.
• Production Asset Finishing: Complete post-processing engine forked and customized from 3DGenStudio, delivering watertight repair, conformal UV unwrapping, PBR material baking, quad retopology, multi-tier LOD cascades, and CoACD convex collision hulls.
• Hardware-Adaptive GPU Doctor: Standalone hardware compatibility and memory execution planner (patcher/doctor.py), guaranteeing 100% native BFloat16 FlashAttention on modern GPUs (sm >= 80) and mathematically exact query-chunked SDPA on pre-Ampere GPUs (sm < 80).

ForMesh3D enforces an immutable master preservation architecture. The raw neural model output is immediately snapshotted at master/source.glb before any downstream finishing operations, guaranteeing zero accidental loss of fine surface detail:

flowchart LR
    %% High-Contrast Styling
    classDef input fill:#262213,stroke:#eab308,stroke-width:2px,color:#fef08a;
    classDef neural fill:#211833,stroke:#a855f7,stroke-width:2px,color:#e9d5ff;
    classDef master fill:#0d242a,stroke:#06b6d4,stroke-width:2px,color:#a5f3fc;
    classDef post fill:#0d271c,stroke:#10b981,stroke-width:2px,color:#a7f3d0;
    classDef export fill:#181c24,stroke:#64748b,stroke-width:2px,color:#f1f5f9;

    IMG["Input Concept Image<br/>(Single Reference)"]:::input
    MODEL["Neural Model Adapter<br/>TRELLIS.2 / Hunyuan3D / TripoSG"]:::neural
    MASTER["master/source.glb<br/>Immutable Raw Mesh<br/>(SHA-256 Verified)"]:::master

    subgraph Finishing ["Production Post-Processing Engine"]
        GATE["1. Topology Gate"]:::post
        REPAIR["2. Hole Repair"]:::post
        DECIMATE["3. Decimation"]:::post
        UV["4. UV Resolver"]:::post
        PBR["5. PBR & Bake"]:::post
        LOD["6. LODs & Physics"]:::post
    end

    OUT["Game-Ready Package<br/>• game_ready.glb<br/>• lod0-lod3.glb<br/>• collision.glb & physics.json"]:::export

    IMG --> MODEL
    MODEL --> MASTER
    MASTER --> GATE
    GATE --> REPAIR
    REPAIR --> DECIMATE
    DECIMATE --> UV
    UV --> PBR
    PBR --> LOD
    LOD --> OUT

The following diagram illustrates the multi-tier system architecture connecting the Next.js studio frontend, FastAPI control plane, VRAM scheduler, neural adapters, and post-processing pipeline:

flowchart TD
    %% Styling Definitions
    classDef gold fill:#262213,stroke:#eab308,stroke-width:2px,color:#fef08a;
    classDef cyan fill:#0d242a,stroke:#06b6d4,stroke-width:2px,color:#a5f3fc;
    classDef purple fill:#211833,stroke:#a855f7,stroke-width:2px,color:#e9d5ff;
    classDef green fill:#0d271c,stroke:#10b981,stroke-width:2px,color:#a7f3d0;
    classDef amber fill:#2d1b0d,stroke:#f59e0b,stroke-width:2px,color:#fde68a;
    classDef slate fill:#181c24,stroke:#64748b,stroke-width:2px,color:#f1f5f9;

    subgraph Client ["Studio Frontend (Next.js 16 : Port 3000)"]
        UI["Unified Studio UI<br/>React 19 + Radix UI + Motion"]:::gold
        VIEWER["Continuous 3D WebGL Viewport<br/>Three.js Persistent Canvas Stage"]:::gold
        STORES["Reactive State Stores<br/>Zustand + TanStack Query"]:::gold
    end

    subgraph Gateway ["API Gateway & Control Plane (FastAPI : Port 7842)"]
        ROUTERS["API Routers<br/>Generation / Retopo / UV / Rigging"]:::cyan
        QUEUE["Distributed Job Queue<br/>Redis 7 + Dual SQLite Sync"]:::cyan
    end

    subgraph Scheduler ["VRAM-Aware Scheduler"]
        GPU_LOCK["GPU Mutual Exclusion<br/>Single Job Concurrency"]:::amber
        MONITOR["Hardware Telemetry<br/>1024 MB Headroom Guard"]:::amber
    end

    subgraph Engines ["Neural 3D Synthesis Engines"]
        HUNYUAN["Hunyuan3D-2.1 Suite<br/>Shape + Paint 2B + Turbo"]:::purple
        TRELLIS["TRELLIS & TRELLIS.2<br/>FlexiCubes Structured Meshes"]:::purple
        TRIPO["TripoSG<br/>High-Fidelity Image-to-Mesh"]:::purple
        TAO["TaoFlowForge<br/>Cascaded Flow Matching"]:::purple
        RETOPO["FastMesh V1K / V4K<br/>Neural Quad Retopology"]:::purple
        RIGGING["UniRig & ARDY<br/>Auto-Rigging & Motion AI"]:::purple
        UNIQUE3D["Unique3D<br/>Multi-View Diffusion"]:::purple
    end

    subgraph PostProcess ["Production Post-Processing Pipeline"]
        CHECKPOINT["source.glb<br/>Immutable Master Raw Mesh"]:::green
        GATE["1. Topology Gate & Audit"]:::green
        HOLE_REPAIR["2. Targeted Hole Repair"]:::green
        DECIMATE["3. Memory-Safe Decimate"]:::green
        UV_RESOLVE["4. Conformal UV Unwrapping"]:::green
        PBR_VAL["5. Tangent Normal & PBR Bake"]:::green
        LOD["6. LOD Cascades (LOD0–LOD3)"]:::green
        PHYSICS["7. CoACD Convex Colliders"]:::green
        QA["8. QA Diagnostic Engine (0-100)"]:::green
    end

    subgraph Delivery ["Game Engine Ready Delivery"]
        ASSET_STORE["backend/storage/models/meshes/<br/>Canonical Asset Hierarchy"]:::slate
        ZIP["Structured ZIP Export<br/>Unreal Engine 5 • Unity • Godot 4"]:::slate
    end

    UI --> STORES
    STORES -->|REST / SSE Stream| ROUTERS
    ROUTERS --> QUEUE
    QUEUE --> GPU_LOCK
    GPU_LOCK --> MONITOR
    MONITOR --> HUNYUAN
    MONITOR --> TRELLIS
    MONITOR --> TRIPO
    MONITOR --> TAO
    MONITOR --> RETOPO
    MONITOR --> RIGGING
    MONITOR --> UNIQUE3D

    HUNYUAN -->|Model Native GLB| CHECKPOINT
    TRELLIS -->|Model Native GLB| CHECKPOINT
    TRIPO -->|Model Native GLB| CHECKPOINT
    TAO -->|Model Native GLB| CHECKPOINT
    UNIQUE3D -->|Model Native GLB| CHECKPOINT

    CHECKPOINT --> GATE
    GATE --> HOLE_REPAIR
    HOLE_REPAIR --> DECIMATE
    DECIMATE --> UV_RESOLVE
    UV_RESOLVE --> PBR_VAL
    PBR_VAL --> LOD
    LOD --> PHYSICS
    PHYSICS --> QA
    QA --> ASSET_STORE
    ASSET_STORE --> ZIP
    ASSET_STORE -.->|Model Stream| VIEWER
    RETOPO -.->|Quad Mesh| ASSET_STORE
    RIGGING -.->|Rigged Bones| ASSET_STORE

The model registry is dynamically configured via backend/config/models.yaml and loaded lazily:

Registry source of truth: the catalog above mirrors backend/config/models.yaml. Only entries with enabled: true are exposed by GET /api/v1/system/models. backend/config/smart_presets.yaml holds the intent presets (mobile, game_ready, cinematic, animation, 3d_print; native is a backend-only sentinel).

ForMesh3D features GPU Doctor (patcher/doctor.py), a lightweight, non-invasive hardware compatibility, precision routing, and memory management subsystem. Built strictly following Ponytail Ultra principles (single compact file, zero unnecessary dependencies, native PyTorch + Hugging Face Accelerate), GPU Doctor resolves hardware heterogeneity between modern cloud GPUs and budget pre-Ampere workstations:

flowchart TD
    %% Styling Definitions
    classDef modern fill:#0d271c,stroke:#10b981,stroke-width:2px,color:#a7f3d0;
    classDef preAmpere fill:#2d1b0d,stroke:#f59e0b,stroke-width:2px,color:#fde68a;
    classDef core fill:#0d242a,stroke:#06b6d4,stroke-width:2px,color:#a5f3fc;
    classDef action fill:#211833,stroke:#a855f7,stroke-width:2px,color:#e9d5ff;

    GPU["GPU Inspection (inspect_gpu)<br/>Compute Capability & VRAM Probe"]:::core
    DECISION{"Compute Capability<br/>sm >= 80 ?"}:::core

    GPU --> DECISION
    DECISION -->|YES: A100 / H100 / RTX 3090 / 4090| MODERN["Rule 1: Upstream Native Mode<br/>• Native BFloat16 Precision<br/>• Official FlashAttention 2 / 3<br/>• Resident Full VRAM Schedule<br/>• Zero Fallback Overhead"]:::modern

    DECISION -->|NO: Tesla T4 / V100 / RTX 2080| PRE["Pre-Ampere Mitigations<br/>• Precision: Native FP16 / BF16 DiT<br/>• Attention: Query-Chunked SDPA<br/>• Memory: Accelerate Offload / low_vram<br/>• Stage-wise Cache Purging"]:::preAmpere

    MODERN --> EXEC["Guarded Inference Execution<br/>(with doctor.track_stage)"]:::action
    PRE --> EXEC

    EXEC --> OK["Clean Mesh Output<br/>(Immutable master/source.glb)"]:::modern
    EXEC -->|Intercepted Exception| ERR{"Error Classifier<br/>(classify_error)"}:::action

    ERR -->|CUDA OOM| REC1["Cache Purge & GC<br/>empty_cache() + ipc_collect()"]:::action
    ERR -->|SDPA Math OOM| REC2["Query Chunking (1024)<br/>Peak Memory: 10GB -> 30MB"]:::action
    ERR -->|Empty Voxels| REC3["Adaptive Top-K Percentile<br/>Fallback Voxel Recovery"]:::action
    ERR -->|Max Retries Exceeded| FAIL["Safe Terminal Error Report"]:::preAmpere

1. Rule 1 Priority (Zero Modern GPU Regression): On modern GPUs (sm >= 80, e.g. A100, RTX 3090/4090, H100), GPU Doctor preserves 100% native BF16 precision and native FlashAttention with zero fallbacks, zero performance penalties, and official README parity.
2. Mathematically Exact Query-Chunked SDPA: On pre-Ampere GPUs (sm < 80), large token sequences (e.g. 15,000+ tokens in TaoFlowForge Stage 1) trigger PyTorch SDPA Math fallback, causing 10.06 GiB OOM crashes. GPU Doctor slices query tokens along the sequence dimension (chunk_size=1024) while evaluating against all key/value tokens. Because softmax normalizes along the key dimension, the output is mathematically identical (diff = 0.0) while peak attention memory drops from 10.06 GiB to ~30 MB across both 3D and 4D tensors.
3. Structured Diagnostics & Bounded Recovery: Tracks stage-by-stage timings, peak VRAM allocations, and classifies exceptions into 7 actionable categories (cuda_oom, unsupported_precision, dtype_mismatch, device_mismatch, attention_backend_failure, sparse_empty_voxels, unknown) with a strict retry limit (max_retries=2) to prevent infinite failure loops.

_{Figure 1: ForMesh3D unified Studio Workspace — live interactive Three.js viewport, real-time geometry telemetry HUD, model adapter selector with hardware VRAM admission, and automated production post-processing toggles.}

The ForMesh3D Studio UI integrates neural generation and mesh finishing into a cohesive desktop-grade web application:

• Interactive Three.js Viewport: Smooth orbital camera controls, perspective/orthographic toggle, wireframe overlay, PBR matcap rendering, and continuous WebGL staging.
• Real-Time Geometry Telemetry HUD: Direct in-viewport telemetry tracking triangle count, vertex count, watertight manifold status, physical bounding box dimensions ($W \times H \times D$), and quality score.
• Hardware-Aware Model Selector: Real-time VRAM estimator comparing model memory reservations with live GPU telemetry (torch.cuda.mem_get_info) to prevent out-of-memory crashes before jobs are queued.
• Production Post-Processing Controls: Toggle automated quad retopology, hole repair, conformal UV unwrapping, normal baking, and collision hull generation without mutating the immutable master/source.glb.

• Generate Studio (/workspace): Image-to-3D generation with reference image intake, model selector, unified Target Polycount, and Output Presets (mobile, game_ready, cinematic, animation, 3d_print, native).
• Texture Studio (/workspace/texture): Multi-view PBR texture painting and PBR map inspection/export (Albedo, Normal, Roughness, Metallic, AO). Paint3D handles 1K/2K, while Hunyuan3D-Paint runs internal RealESRGAN enhancement for 4K/8K.
• Retopology & Remesh (/workspace/remesh): FastMesh quad-dominant retopology with V1K and V4K target presets.
• UV Unwrapping (/workspace/uv): Automated conformal seam placement and atlas chart packing.
• Mesh Segmentation (/workspace/segment): Semantic part decomposition interface.
• Animation & Motion (/animation): UniRig bipedal armature generation and ARDY motion synthesis.
• Jobs & Run Inspector (/workspace/jobs): Real-time progress tracking, step telemetry, and VRAM monitoring.
• Admin & Model Registry (/admin?tab=models): Live GPU health, temperature, and adapter configuration.
• Database Administration (/admin?tab=database): Cross-store statistics (SQLite/Redis/queue/file-metadata/disk), read-only Redis key inspector, and paginated jobs table with per-row cancel/delete.

Raw AI generative meshes typically suffer from non-manifold triangles, missing UV layouts, dense topological noise, and absence of physics colliders. ForMesh3D's post-processing engine (ported and enhanced from 3DGenStudio) automates asset finishing:

backend/storage/models/meshes/<asset_name>_<job_id>/
├── master/
│   └── source.glb              # Immutable master raw mesh (SHA-256 verified)
├── game_ready/
│   └── <asset_name>_<job_id>.glb # Production engine-ready model
├── lods/
│   ├── lod0.glb                # LOD0 (100% detail)
│   ├── lod1.glb                # LOD1
│   ├── lod2.glb                # LOD2
│   └── lod3.glb                # LOD3 (at most 4 levels; ratios follow LOD preset)
├── collision/
│   └── collision.glb           # Watertight CoACD convex hull
├── textures/                   # PBR texture maps (Albedo, Normal, Roughness, Metallic, AO)
├── previews/                   # Rendered thumbnail images
└── metadata/
    ├── asset.json              # Canonical asset manifest
    ├── quality_report.json     # QA 0-100 score & stage trace
    └── physics.json            # Mass, center of mass, inertia tensor

1. Topology Gating & Clean Passthrough: Evaluates 14 geometric and topological metrics (non-manifold edges/vertices, boundary holes, floater ratio, aspect-ratio percentiles). Clean meshes bypass repair entirely; small boundary loops are routed to targeted repair.
2. Targeted Hole Repair: Traverses directed boundary loops and triangulates small holes ($\le 50$ vertices) with fan triangulation without altering or smoothing uncorrupted surfaces.
3. Memory-Safe Staged Decimation: Feature-preserving QEM decimation protecting crease edges ($>35^\circ$); meshes exceeding 2M triangles engage staged 50% chunked decimation with live psutil RAM tracking (80% headroom cap) and aggressive garbage collection.
4. Centralized UV Backend Resolver: Single-point resolver automatically routing meshes $\ge 500\text{k}$ triangles to GPU PartUV (when CUDA and 7GB VRAM are free), falling back to high-throughput CPU/GPU xatlas with 0% overlap and strict $[0, 1]$ bounds.
5. Tangent Normal Bake & 5-Channel PBR Validation: Tangent-space normal baking (OpenGL Y+ convention) from high-poly master, validating non-degenerate textures, packed roughness (G) / metallic (B) channels, and atlas space utilization.
6. CoACD Physics Colliders & WebSim: Computes approximate convex decomposition for game engine colliders with in-browser Rapier3D physics preview.

• OS: Linux (Ubuntu 20.04, 22.04, or 24.04 recommended) or Windows WSL2.
• GPU: NVIDIA GPU with CUDA 12.4+ (minimum 8GB VRAM for basic models, 16GB–24GB+ recommended).
• Node Environment: Bun installed.
• Python: Python 3.10 via Conda (conda create -n 3daigc-api python=3.10).

git clone --recurse-submodules https://github.com/Silentzx2/ForMesh3D.git
cd ForMesh3D

# Install frontend dependencies with Bun
bun install

# Automated setup prepares the environment, builds C++/CUDA kernels,
# installs backend dependencies, and initializes the thirdparty submodule
bash scripts/setup.sh

Download pre-trained weights for the models you wish to use:

# Download core model checkpoints
bash backend/scripts/download_models.sh

# Launch both backend (Port 7842) and Next.js frontend (Port 3000)
bash scripts/start.sh

Open http://localhost:3000 in your browser.

• Frontend Studio: http://localhost:3000
• Backend API: http://localhost:7842
• Interactive Swagger Docs: http://localhost:7842/docs
• Health Endpoint: http://localhost:7842/api/v1/system/health

From the repository root, build and start the containerized backend stack:

docker compose -f docker-compose.yml up --build -d

The FastAPI backend exposes comprehensive REST and SSE streaming endpoints:

ForMesh3D maintains rigorous unit, integration, and regression test suites across frontend and backend:

# Backend Pytest Suite (36 passed)
# Includes GPU Doctor hardware diagnostics & chunked SDPA tests (28 passed)
# and TRELLIS.2 mesh validation & domain bounding box rejection tests (8 passed)
pytest backend/tests/

# Frontend Bun Test Suite (60 passed across 11 test files)
bun test

# Verify clean compilation across all Python backend & patcher modules
python3 -m py_compile patcher/doctor.py patcher/__init__.py backend/tests/*.py

# Frontend type and lint checks
npx tsc --noEmit
bun run lint

# Verify shell script syntax
bash -n manager.sh backend/scripts/*.sh scripts/*.sh

Live Verification Status (November 5, 2026):

• Pytest Backend: 36/36 passed (backend/tests/test_gpu_doctor.py + backend/tests/test_trellis2_mesh_validation.py).
• Bun Frontend: 60/60 passed across 11 test files.
• Python Bytecode: 100% clean compilation on all backend, adapter, thirdparty, and patcher files.
• Live GPU Inference Verification: Hunyuan3D-Shape v2.1 (PASS, 935k faces), Hunyuan3D DiT Mini Turbo (PASS, 758k faces), and Unique3D (PASS, lightweight geometry mode). Status: STABLE & LOCKED.

• ForMesh3D Core: Licensed under the Apache License 2.0.
• Post-Processing Pipeline: Ported and adapted from visualbruno/3DGenStudio under the 3D Gen Studio Community License. See backend/postprocess/THIRD_PARTY_LICENSE.md.
• Backend API Gateway Base: Forked and modernized from FishWoWater/3DAIGC-API.
• Neural Model Checkpoints: Source and checkpoint terms are controlled by their respective upstream authors. See the ThirdParty licensing directory.