ForMash3D

Open-Source Generative 3D Mesh 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 https://github.com/Silentzx2/ForMash3D.git → bun install → bash scripts/start.sh → Open http://localhost:3000

---

🌟 Overview & Product Vision

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

ForMash3D unifies neural 3D generation, asset finishing, validation, and export into one self-hosted workflow for 3D technical artists, game developers, and researchers:

• 100% Private & Self-Hosted: Run generation locally on NVIDIA GPUs without subscriptions, cloud queues, or uploading proprietary concept art to external servers.
• Immutable Source Preservation: Model-native generation is snapshotted at master/source.glb before production optimization or decimation.
• Production Asset Finishing: Features a complete post-processing pipeline forked and customized from 3DGenStudio, delivering watertight repair, conformal UV unwrapping, PBR material baking, quad retopology, multi-tier LOD cascades, and CoACD convex physics collision hulls.

---

[!WARNING]

⚖️ Licensing, Commercial & SaaS Advisory (Important)

1. Core Repository License: ForMash3D's original code (orchestrator, API gateway, scheduler, and Next.js studio UI) is open-source under the Apache License 2.0.
2. Post-Processing Provenance: The mesh post-processing engine (backend/postprocess/) was forked and customized from visualbruno/3DGenStudio under the 3D Gen Studio Community License. See backend/postprocess/THIRD_PARTY_LICENSE.md.
3. Commercial Ownership of Outputs: You own 100% of the 3D meshes, textures, rigs, and assets generated with ForMash3D. You are completely free to use, monetize, sell, or include them in commercial games and software without restrictions.
4. Notice for Commercial & SaaS Implementors:
   • The Apache 2.0 license applies strictly to ForMash3D's original code. We do not own or re-license the underlying third-party models, research weights, or ported submodules.
   • The ported 3DGenStudio post-processing pipeline prohibits hosting the software as a paid public/private commercial SaaS service without explicit written consent from the upstream author (visualbruno).
   • Individual model checkpoints (e.g. Hunyuan3D-2.1, FastMesh, TripoSG) carry their respective upstream research, academic, or non-commercial licenses (see backend/thirdparty/LICENSE and individual backend/thirdparty/<model>/LICENSE files).
   • Do NOT blindly deploy or redistribute ForMash3D as a paid commercial product or SaaS without auditing and complying with the respective licenses of each integrated model and component!

[!NOTE]

🛡️ Repository Rules & Engineering Standards

All contributions and architectural modifications must comply strictly with RULES.md:

• Ponytail Minimalist Architecture: YAGNI-first, reuse existing helpers and standard library, shortest correct diffs, zero speculative abstractions.
• Documentation Integrity: Any pipeline or backend modification must be reflected across all Docs/*.md guides immediately.
• Source Integrity: Downstream post-processing must operate on derived data and never mutate master/source.glb.

---

📊 Core Capability Map

🔄 End-to-End Asset Generation Pipeline

ForMash3D 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:

   INPUT                     NEURAL GENERATION               CANONICAL CHECKPOINT
┌─────────────────────┐    ┌───────────────────────────┐    ┌──────────────────────────┐
│  • Single Image     │───►│  Neural Model Adapters:   │───►│ master/source.glb        │
│                     │    │  TRELLIS / Hunyuan3D 2.1  │    │ (Immutable Master Mesh)  │
│                     │    │  TripoSG                  │    │ Preserves Raw Topology   │
└─────────────────────┘    └───────────────────────────┘    └────────────┬─────────────┘
                                                                          │
 ┌───────────────────────────────────────────────────────────────────────┘
 │  PRODUCTION POST-PROCESSING & ENGINE FINISHING (Ported & Enhanced from 3DGenStudio)
 ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ 1. Repair       │───►│ 2. Retopo       │───►│ 3. UV & Bake    │───►│ 4. LOD Cascade  │
│ Watertightness  │    │ FastMesh Quads  │    │ Conformal UV    │    │ LOD0: 100%      │
│ Non-Manifold Fix│    │ AutoRetopo Def. │    │ Optional PBR Map│    │ LOD1: 50%       │
│ Boundary Guard  │    │ Feature Angle   │    │ Hunyuan ESRGAN  │    │ LOD2: 25% / 12% │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └────────┬────────┘
                                                                               │
 ┌────────────────────────────────────────────────────────────────────────────┘
 ▼
┌─────────────────┐    ┌─────────────────┐    ┌────────────────────────────────────────┘
│ 5. Physics      │───►│ 6. QA Engine    │───►│ GAME-READY EXPORT PACKAGE              │
│ CoACD Convex    │    │ 0-100 Score     │    │ • game_ready.glb (Unreal / Unity/Godot)│
│ Decomposition   │    │ Stage Snapshots │    │ • lods/ (lod0.glb - lod3.glb)          │
│ Rapier3D WebSim │    │ Quality Trace   │    │ • collision.glb & physics.json         │
└─────────────────┘    └─────────────────┘    │ • Structured Engine-Ready ZIP Archive  │
                                               └────────────────────────────────────────┘

---

🏗️ System Architecture

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 with High-Contrast Colors
    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 Dynamic-Tab 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 and Control Plane FastAPI port 7842]
        ROUTERS["API Routers<br/>Generation / Retopo / UV / Rigging"]:::cyan
        QUEUE["Distributed Job Queue<br/>Redis 7 + Single-Worker Memory"]:::cyan
    end

    subgraph Scheduler [VRAM-Aware Multi-Process 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
        RETOPO["FastMesh V1K / V4K<br/>Neural Quad Retopology"]:::purple
        EXTRAS["Additional Mesh Tools<br/>No provider configured"]:::purple
        RIGGING["UniRig & ARDY<br/>Auto-Rigging & Motion AI"]:::purple
        UNIQUE3D["Unique3D<br/>Single-Image Multi-View Diffusion"]:::purple
    end

    subgraph PostProcess [Production Post-Processing Core based on 3DGenStudio]
        CHECKPOINT["source.glb<br/>Immutable Master Raw Mesh"]:::green
        REPAIR["Watertight Repair<br/>Boundary Component Guard"]:::green
        SIMPLIFY["PyMeshLab Decimator<br/>Texture-Preserving Fallback"]:::green
        AUTORETOPO["Adaptive AutoRetopo<br/>Feature Crease Preservation"]:::green
        BAKE["Conformal UV & Bake<br/>xatlas UV Parameterization"]:::green
        LOD["LOD Cascades<br/>LOD0 to LOD3 with meshopt"]:::green
        PHYSICS["Physics Colliders<br/>CoACD Convex Hulls"]:::green
        QA["QA Diagnostic Engine<br/>0-100 Quality Trace"]:::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

    %% Clean Node-to-Node Data Connections
    UI --> STORES
    STORES -->|REST / SSE Stream| ROUTERS
    ROUTERS --> QUEUE
    QUEUE --> GPU_LOCK
    GPU_LOCK --> MONITOR
    MONITOR --> HUNYUAN
    MONITOR --> TRELLIS
    MONITOR --> TRIPO
    MONITOR --> RETOPO
    MONITOR --> EXTRAS
    MONITOR --> RIGGING
    MONITOR --> UNIQUE3D

    HUNYUAN -->|Model Native GLB| CHECKPOINT
    TRELLIS -->|Model Native GLB| CHECKPOINT
    TRIPO -->|Model Native GLB| CHECKPOINT
    EXTRAS -->|Model Native GLB| CHECKPOINT

    CHECKPOINT --> REPAIR
    REPAIR --> SIMPLIFY
    SIMPLIFY --> AUTORETOPO
    AUTORETOPO --> BAKE
    BAKE --> 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

---

🤖 Supported Model Catalog

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

---

⚙️ Production Post-Processing Engine

Raw AI generative meshes typically suffer from non-manifold triangles, missing UV layouts, dense topological noise, and absence of physics colliders. ForMash3D'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
├── game_ready/
│   └── <asset_name>_<job_id>.glb # Production engine-ready model
├── lords/
│   ├── lod0.glb                # LOD0 (100% detail)
│   ├── lod1.glb                # LOD1 (50% reduction)
│   ├── lod2.glb                # LOD2 (25% reduction)
│   └── lod3.glb                # LOD3 (12.5% reduction)
├── 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

Core Finishing Highlights:

1. Texture-Preserving Decimation: Powered by PyMeshLab with custom wedge UV remapping. If complex non-manifold geometry prevents decimation, the engine safely falls back to passthrough without dropping materials.
2. Structural AutoRetopo: Triggers on structural boundary defects (e.g. boundary component holes > 30 edges) with feature-angle preservation (25.0°) and controlled smoothing.
3. CoACD Physics Colliders: Computes approximate convex decomposition for immediate rigid-body physics in game engines.
4. Three.js & Rapier3D In-Browser Simulator: Test gravity, bouncy collisions, and mass properties directly in the workspace viewer before exporting.

---

🛠️ Technology Stack

---

📦 Installation & Quick Start

Prerequisites

• 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).

The shared Python runtime is version-pinned for supported model adapters: Transformers 4.48.3 (required by Hunyuan3D Mini Turbo and PEFT), Diffusers 0.30.3, and PyTorch 2.6.0 with CUDA 12.4. Use bash scripts/setup.sh rather than installing model dependencies individually.

1. Clone & Frontend Setup

git clone https://github.com/Silentzx2/ForMash3D.git
cd ForMash3D

# Install frontend dependencies with Bun
bun install

2. Backend Environment & Setup

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

3. Model Weights & Checkpoints

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

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

4. Running the Studio

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

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

Services:

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

Docker Compose (NVIDIA GPU)

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

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

Compose builds from the repository root. The image keeps backend code under /app/backend, adds it to PYTHONPATH, and launches the scheduler from that path. Put model weights in backend/pretrained/; generated assets are persisted in backend/storage/, shared by the API and scheduler.

The single-container RunPod image uses the same repository-root build context: docker build -f backend/Dockerfile.runpod -t formash3d-runpod .. Its supervisor runs the API and scheduler from /app/backend and keeps Redis on localhost port 6380.

---

🎮 Studio Workspace Modules

The ForMash3D workspace provides a comprehensive suite of creative 3D tools:

• Generate Studio (/workspace): Image-to-3D generation with model selector, VRAM estimator, and step configuration.
• 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 its internal RealESRGAN enhancement for 4K/8K; this is automatic, not a separate UI setting.
• 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; no model adapter is currently configured.
• Mesh Editing (/workspace/edit): Workspace/API scaffolding remains, but no mesh-editing model adapter is currently configured.
• 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, paginated jobs table with per-row cancel/delete and multi-select bulk delete, plus typed-confirmation clear actions for jobs and file metadata.

---

🔌 API Endpoints Reference

The FastAPI backend exposes comprehensive REST and SSE streaming endpoints:

---

🛠️ Verification & Test Suite

ForMash3D maintains rigorous unit, integration, and regression test suites:

# Run all backend unit & regression tests
FORMASH_POSTPROCESS_E2E=1 PYTHONPATH=backend pytest backend/tests/ -v

# Verify clean compilation across all Python modules
python3 -m compileall -q backend/

# Run frontend type and lint checks
npx tsc --noEmit
bun run lint

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

Verification status: Runtime verification must be run on the supported Python 3.10/GPU environment; this checkout's static audit does not claim a live test result.

---

🔍 Frequently Asked Questions (FAQ)

How does ForMash3D protect source quality?

Source generation uses model-specific inference schedules and source-density settings. The scheduler strips production-only face, decimation, remesh, LOD, physics, and paint orchestration controls before adapter inference. The resulting master/source.glb is immutable; downstream production budgets operate on derived artifacts only.

Can I use ForMash3D commercially or deploy it as a paid SaaS service?

For Outputs: Yes! You own 100% of all 3D meshes, textures, rigs, and assets generated with ForMash3D. You may use them in commercial video games, 3D printing, VFX, or digital storefronts.

For Code & Hosting: While ForMash3D's original orchestrator is open-source under Apache 2.0, the codebase incorporates ported engines (such as the 3DGenStudio post-processing pipeline under the 3D Gen Studio Community License) and external neural model weights that carry non-commercial or academic research restrictions. You may NOT sell the unmodified software or host it as a paid commercial SaaS service without explicit author permission. Please review backend/thirdparty/LICENSE and backend/postprocess/THIRD_PARTY_LICENSE.md for details.

Can I generate clean quad-topology meshes for game animation?

Yes. ForMash3D natively integrates FastMesh (V1K for rapid prop prototyping and V4K for hero characters) alongside an adaptive AutoRetopo pipeline. Unlike raw generative outputs that yield messy triangle soups, ForMash3D outputs clean quad-dominant edge loops with preserved feature creases, ready for skeletal auto-rigging and subdivision.

How does ForMash3D handle PBR texturing and baking?

ForMash3D features Hunyuan3D-Paint-v2.1, a 2B parameter diffusion checkpoint that projects multi-view high-resolution textures onto 3D geometry with automated Real-ESRGAN x4+ super-resolution. The engine bakes complete PBR material channels (Albedo, Tangent Normal, Roughness, Metallic, and Ambient Occlusion) onto clean conformal UV layouts.

Can ForMash3D run 100% offline without internet?

Yes. Once your model checkpoints are downloaded via bash backend/scripts/download_models.sh, ForMash3D operates completely offline. No telemetry, prompts, reference images, or generated models are ever transmitted to any external server, ensuring complete data privacy and NDA compliance for commercial game studios.

What GPU hardware is required to run ForMash3D?

ForMash3D runs on modern NVIDIA GPUs supporting CUDA 12.4+:

• Lightweight Models (6GB–10GB VRAM): TripoSG, Hunyuan3D-DiT-v2-mini-Turbo (runs comfortably on RTX 3060, 4060, RTX 2080).
• Standard Models (12GB–16GB VRAM): TRELLIS, FastMesh (runs on RTX 3080, 4070, 4080, T4, L4).
• Heavy & High-Poly Models (24GB+ VRAM): TRELLIS.2, Hunyuan3D-Paint 2B (runs on RTX 3090, 4090, A10, A100).

What file formats can ForMash3D export for game engines?

ForMash3D exports standard GLB / glTF 2.0, OBJ, STL, and FBX (via isolated Blender automation). Downloaded ZIP archives are structured specifically for Unreal Engine 5, Unity, and Godot 4, containing game-ready meshes, LOD cascades (lod0.glb–lod3.glb), convex collision hulls (collision.glb), and portable physics metadata (physics.json).

---

🏷️ Recommended GitHub Repository Topics

3d, 3d-generation, 3d-mesh-generation, tripo-ai, image-to-3d, mesh-generation, ai-3d, generative-ai, generative-3d, neural-3d, self-hosted, self-hosted-ai, gpu-accelerated, pbr-textures, retopology, quad-mesh, fastmesh, trellis, hunyuan3d, unreal-engine, unity, godot, game-ready, physics-colliders, open-source-3d

---

Centralized Runtime Logging

All project-managed runtime output is consolidated in logs/master.log: Python/API logging, scheduler and worker events, jobs, Next.js server/build output, startup scripts, and Redis when ForMash3D manages or can reconfigure the local Redis instance. The file is append-only while the app runs and does not rotate into numbered sibling logs.

Use ./manager.sh logs or tail -f logs/master.log. The Admin Logs tab and /api/v1/system/logs/stream read this same file. Docker and Docker Compose persist it through the repository-root logs/ mount. A separately managed remote Redis service keeps its own logs on its host.

---

📚 Documentation Index

---

📄 License & Attribution

• ForMash3D 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: Individual neural model architectures are subject to their respective original authors' licenses (Hunyuan3D, TRELLIS, TripoSG, FastMesh, etc.). See backend/thirdparty/LICENSE and individual backend/thirdparty/<model>/LICENSE files for full attributions and terms.

---

Recent Fixes (2026-10-05)

• Fixed Minified React error #130 on settings page by adding error handling for missing workspace context.
• Made "smash mash gen" feature visible in UI by adding fallback to hardcoded smart presets when API fails.

Runtime note

Mesh tools are part of the main FastAPI runtime at /api/v1/mesh-tools/*. The default startup no longer launches a separate port 8200 mesh-tools service. Job progress is read from durable job state; mesh-tool operations may stream operation-level SSE progress.

Phase 1 Production Automation

ForMash3D's normal Image → 3D workflow now includes optional production automation without a second pipeline:

• Generation Preview with reusable preprocessing artifacts, adaptive low-resolution enhancement, and provenance.
• Smart Intent presets for Game Ready, Cinematic, Animation, 3D Print, and Mobile with deterministic backend model selection.
• Printability QA with optional auto-repair inside the existing post-processing path.
• Auto-Rig through the existing UniRig adapter after final production processing, with explicit success/degraded state.

These capabilities reuse the existing scheduler, image editor, post-processing, history, and artifact-delivery infrastructure.

High-Fidelity Generation Architecture

ForMash3D now treats the generated master mesh as the immutable high-fidelity asset and produces optimized/game-ready derivatives from it. Model selection remains additive and capability-aware, so existing models are retained rather than replaced. The scheduler can use explicit multi-GPU placement for compatible pipelines and scales CPU-side work from the available core count while preventing worker oversubscription.

Quality diagnostics can compare derivatives to the master and can use reference-mesh metrics when ground truth is available. Final GPU/OOM validation remains hardware-specific.

High-Fidelity Runtime Hardening — 2026-10-08

ForMash3D now uses a normalized model capability contract for deterministic routing, model-aware preprocessing and resource admission. The scheduler can consider aggregate VRAM only for adapters that explicitly declare a supported multi-GPU strategy. CPU worker/thread policy is auto-scaled from available logical cores with environment overrides.

Production results keep the immutable source master separate from optimized derivatives and now include final QA/LOD/fidelity diagnostics. A lightweight offline A/B benchmark is available for controlled same-input comparisons; without a real reference mesh, generated-vs-generated geometry metrics remain diagnostic.