🚀 Local3D Studio — Universal 16GB-Safe AI-to-3D Manufacturing & MCP Server

Local3D Studio is an open-source, production-grade 3D generative manufacturing suite and Model Context Protocol (MCP) server. It converts raw text prompts and 2D photos into high-definition, watertight 3D-printable figurines (.stl), modular keyed assemblies (.3mf), and game-ready digital assets (.glb).

Designed as a 100% local-first, zero-cloud alternative to platforms like Meshy AI and Tripo3D, Local3D Studio executes entirely on consumer hardware within a strict 16 GB unified RAM/VRAM budget—without requiring proprietary CUDA compilation flags or mandatory background daemon servers. By using the client AI's native visual generator (or user-provided photos) for 2D concepts, 100% of your 16 GB of RAM/VRAM is dedicated exclusively to 3D neural reconstruction (Hunyuan3D-2) and headless Blender manufacturing.

📖 Read in Italian / Leggi in Italiano: README_IT.md
🏛️ Architecture Deep-Dive: docs/ARCHITECTURE.md
🔌 MCP Client Setup Guide: docs/MCP_GUIDE.md
🌐 MCP Directories & Community: docs/SUBMISSIONS.md

🌟 Key Feature Highlights

1. Complete Meshy AI Open-Source Alternative (15 Native MCP Tools)

Local3D Studio provides a full local replacement for commercial 3D generation suites:

• Direct Image-to-3D (direct_image_to_3d): 1-click transformation of any 2D concept or photo into a 3D mesh using single_hero_34 (isometric props/weapons) or multiview_turnaround (full 360° characters).

• Auto Split & Assembly Keying (auto_split_model): Automatically cuts models into keyed parts (Head, Torso, Arms, Legs) with 0.25mm assembly tolerances, manifold watertight capping, exploded .glb view, and native multi-color .3mf for Bambu Studio & OrcaSlicer AMS.

• Humanoid Pose Guidance (canonicalize_humanoid_pose): Eliminates limb fusion (mesh webbing) by standardizing character inputs into A-Pose (35°-45°), T-Pose (90°), Action Pose, or Natural Pose with visual vector angle verification overlays.

• AI Retopology Engine (retopologize_mesh): Generates clean topology via Quadriflow 100% All-Quad (ready for rigging/subdivision) or Decimate Triangle Collapse (exact polygon budget for game engines).

• PBR Texture Baking (bake_pbr_textures): Bakes tangent-space Normal maps and Ambient Occlusion (AO) up to 4096px via headless Blender Cycles, exporting a production PBR .glb.

2. Pure In-Process MCP Execution (Zero Daemons Required)

Unlike systems that require running background FastAPI servers on localhost:8000, Local3D Studio's MCP server (server.py) communicates directly over stdio. Connect it to Google Antigravity, Claude Desktop, Cursor, or Continue.dev simply by pointing your client configuration to server.py or run_mcp.sh.

3. Universal Hardware Auto-Detection & Dynamic Tiering

Automatically inspects system capabilities (psutil + PyTorch device inspection) and selects one of 4 auto-scaling performance tiers:

• Apple Silicon (macOS): Native mps backend with torch.float16.

• AMD Radeon (Windows / Linux): Native AMD ROCm/HIP (torch.version.hip) or DirectML (torch-directml), completely free of CUDA lock-in.

• NVIDIA GeForce / RTX: Native cuda backend with SDPA attention.

• Blender Discovery: Autonomously locates Blender across macOS, Windows, and Linux.

4. Multi-View Turnaround Calibration (tools/multiview_aligner.py)

Eliminates rear-side hallucinations and occlusion:

• Connected-Component Isolation: Eliminates adjacent panel bleed-over using alpha mask segmentation (scipy.ndimage).

• Y-Bounding-Box Lock: Standardizes character height to 400px on a 512x512 canvas, locking the feet to $Z=0$ ($Y=456$) and crown to $Y=56$.

• CLAHE Normal Enhancement: Enhances fine surface relief in albedo textures before 3D reconstruction.

5. Production 3-Step Protocol & Hard Approval Gate

• Prompt Compiler (compile_3d_master_prompt): Generates an ultra-detailed, photogrammetry-grade prompt in the Meshy AI Single-Master 3/4 profile with strict anti-occlusion directives (A-pose, separated limbs, zero smoke, zero auras, zero pedestals).

• Native Client AI 2D / User Photo (100% RAM Dedicated to 3D): Fully decouples 2D concept generation to the client AI assistant (e.g. Antigravity's native multimodal generator) or user-supplied reference photos. By eliminating local 2D diffusion pipelines, 100% of the 16 GB unified RAM/VRAM budget is dedicated to 3D neural reconstruction (Hunyuan3D-2) and headless Blender manufacturing, completely avoiding system freezes and maximizing polygon fidelity.

• Hard Approval Gate: Execution strictly pauses after saving output/<name>_concept.png. The agent must display the concept and wait for explicit user confirmation before proceeding.

• Direct 3D Reconstruction (direct_image_to_3d): Preprocesses the approved image with background removal (rembg_engine.py), CLAHE local contrast, and $Z=0$ ground lock, followed by isolated neural 3D reconstruction and headless Blender manufacturing.

• Tempfile Hygiene: Intermediate texture slices, masks, and raw neural meshes are kept inside tempfile.TemporaryDirectory(). Only the final .stl, .glb, .3mf, and lookdev_sheet.png are written to output/.

Related MCP server: tripo-mcp-cn

📂 Repository Structure

Local3D-Studio/
├── .env.example                     # Reference environment configuration
├── .gitignore                       # Git ignore for virtualenvs, caches, outputs
├── LICENSE                          # MIT Open Source License
├── CONTRIBUTING.md                  # Contribution guidelines & code standards
├── README.md                        # English Master Documentation
├── README_IT.md                     # Italian Master Documentation
├── requirements.txt                 # Universal dependencies (zero C++ build flags)
├── setup_env.py                     # Universal installer & hardware bootstrapper
├── server.json                      # Official MCP Catalog Specification Manifest
├── run_mcp.sh / .bat                # In-process stdio MCP server launchers
├── update.sh / .bat                 # One-click automated updater scripts
├── start_worker.sh / .bat           # Optional Web Studio GUI launchers
├── server.py                        # Root MCP Server & Unified CLI (15 Native Tools)
├── worker_api.py                    # Optional FastAPI Web Studio & Three.js server
│
├── core/                            # Hardware abstraction, diagnostics & client layer
│   ├── __init__.py
│   ├── config.py                    # Environment variables & directory paths
│   ├── hardware_backend.py          # HardwareManager (MPS / ROCm / CUDA / 4 Tiers)
│   ├── diagnostics.py               # Local3D Doctor diagnostic & health inspection
│   ├── client_setup.py              # Automated multi-client setup & skill deployment
│   ├── updater.py                   # Automated GitHub release pull & dependency sync
│   ├── response_envelope.py         # Standardized MCP result and error contracts
│   ├── memory.py                    # VRAM/RAM garbage collector & cache cleaner
│   └── client.py                    # Unified REST client (optional LAN offload)
│
├── skills/                          # Bundled AI Agent Skills
│   └── local3d-studio/
│       ├── SKILL.md                 # Production 3-Step Protocol for Antigravity
│       └── references/              # Slicer & hardware tier reference guides
│
├── tools/                           # Modular Generative & Manufacturing Engines
│   ├── __init__.py
│   ├── prompt_enhancer.py           # Dynamic style router & Meshy AI prompt compiler
│   ├── pose_canonicalizer.py        # Humanoid Pose Guidance (A-Pose/T-Pose overlay)
│   ├── concept_engine.py            # Concept engine & fallback generator
│   ├── rembg_engine.py              # Pure Python background removal (u2net/ONNX)
│   ├── multiview_aligner.py         # Anti-bleed & Y-bounding-box lock calibration
│   ├── neural_3d_engine.py          # Hunyuan3D-2 shape generation (Mini & Full)
│   ├── blender_pipeline.py          # Blender headless remesh, LookDev, retopo, PBR
│   ├── model_splitter.py            # Auto Split, watertight capping, 3MF AMS export
│   └── pipeline_engine.py           # Master execution pipeline & state gate manager
│
├── frontend/                        # Web Studio Three.js GUI (Optional)
│   ├── __init__.py
│   └── web_viewer.py                # Three.js 3D viewport, wireframe inspect, telemetry
│
├── docs/                            # In-depth technical guides
│   ├── ARCHITECTURE.md              # Technical deep-dive & subsystem diagrams
│   └── MCP_GUIDE.md                 # Client setup (Antigravity, Claude, Cursor)
│
└── output/                          # Production deliverables (.stl, .glb, .3mf)
    └── .gitkeep

⚡ Quickstart Guide

1. Installation

git clone https://github.com/Jaco2308/Local3D_Studio.git
cd Local3D_Studio

# Run the universal installer (auto-detects Apple Silicon, AMD ROCm, NVIDIA CUDA)
python3 setup_env.py

setup_env.py automatically:

1. Detects your OS and GPU accelerator.

2. Installs the matching PyTorch wheels (mps, rocm, cuda, or cpu).

3. Installs requirements (mcp, trimesh, rembg, scipy, psutil, fastapi, transformers).

4. Autonomously locates your Blender installation.

5. Initializes your .env configuration file.

2. Universal local3d CLI Suite

Inspired by the REA architecture, Local3D Studio provides a system-wide unified CLI command (local3d):

# 1. Automated Health Diagnostics (Blender, PyTorch, Memory Tiers, MCP Client drift)
local3d doctor

# 2. Automated 1-Click Update (GitHub release sync, pip dependencies, skill refresh)
local3d update
# (or double-click update.bat on Windows / ./update.sh on macOS/Linux)

# 3. 1-Command Automated MCP Client Registration & Skill Deployment
local3d setup --client antigravity
local3d setup --client claude_desktop
local3d setup --client cursor

# 4. View Active Hardware Telemetry & Performance Tier
local3d status

# 5. Start Native Stdio MCP Server
local3d mcp

3. Connecting to Your MCP Client

Local3D Studio MCP Server runs 100% locally in-process over stdio.

You can configure your client automatically with:

local3d setup --client antigravity
# Supported clients: antigravity, claude_desktop, cursor, vscode, gemini_cli

Or manually add Local3D Studio to your client's configuration file:

{
  "mcpServers": {
    "local3d": {
      "command": "/absolute/path/to/Local3D-Studio/.venv/bin/python",
      "args": [
        "/absolute/path/to/Local3D-Studio/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

For complete configuration examples for Antigravity, Claude Desktop, Cursor, Continue.dev, and Windsurf, see docs/MCP_GUIDE.md.

3. Optional: Interactive Three.js Web Studio GUI

If you want to view models in a web browser with drag & drop uploads, wireframe inspection, and real-time hardware telemetry:

# macOS / Linux:
./start_worker.sh

# Windows:
start_worker.bat

Then open http://localhost:8000 in your web browser.

🛠️ MCP Tools Reference (Complete 15-Tool Suite)

🖨️ Bambu Lab / OrcaSlicer Multi-Color AMS Workflow

When using auto_split_model:

1. Local3D Studio splits your mesh into anatomical components (Head, Torso, Arms, Legs).

2. Generates individual watertight .stl files in output/<name>_parts/ with 0.25mm keyed male/female pins.

3. Automatically writes a unified .3mf file with pastel vertex color assignments.

4. Drag & drop the generated <name>_split.3mf directly into Bambu Studio or OrcaSlicer:

   • The slicer will ask: "Load these objects as a single object with multiple parts?" -> Click Yes.

   • Assign filament slots (AMS Slot 1, 2, 3, 4) to each part in one click.

   • Slice and print without assembly glue or manual painting!

🌐 MCP Directories & Ecosystem

Local3D Studio is built to seamlessly integrate with any standard Model Context Protocol client:

1-Click Install via Smithery.ai

npx -y @smithery/cli install @Jaco2308/Local3D_Studio --client claude

Official Registries & Communities

• Model Context Protocol Servers: Submitted to modelcontextprotocol/servers community listings.

• MCP Servers Directory: Indexed on mcpservers.org.

• Smithery Registry: Live on smithery.ai.

• Reddit Communities: Join discussions on r/mcp, r/BambuLab, and r/3Dprinting.

• Complete launch guides and directory PR templates: docs/SUBMISSIONS.md.

🤝 Contributing

We welcome community contributions, bug reports, and pull requests! Please read our CONTRIBUTING.md for architectural guidelines, manifold geometry invariants, and code formatting rules.

📄 License

Local3D Studio is released under the MIT License. See LICENSE for details. Free for personal, commercial, and research use.