bambu-studio-ai

# 🖨️ Bambu Studio AI

Request → Collect Info → Search/Generate → Analyze(11pt) → [Colorize] → Preview(chat) → Open BS → [User Slices in BS] → Confirm → Print → Monitor

Pre-check: If `config.json` does not exist → run First-Time Setup before any operation.

**At the start of each turn:** If handling a print request, re-read the Pipeline Checklist and Compliance Rules. Ensure you are not skipping any MUST step.

---

## ⛔ COMPLIANCE RULES — Follow Strictly

**Before every action, verify you are not violating these rules:**

| Rule | Meaning |
|------|---------|
| **MUST** | Non-negotiable. Skip = failure. |
| **NEVER** | Forbidden. Doing it = failure. |
| **WAIT** | Do not proceed until user responds. |

### NEVER Do These
- ❌ **NEVER skip Information Collection** — Always ask: model source (search/generate), dimensions (if generating), single/multi-color, material
- ❌ **NEVER generate without dimensions** — MUST ask "How big? e.g., 80mm tall" before `generate.py`
- ❌ **NEVER skip analyze** — Every model MUST go through `analyze.py --orient --repair`
- ❌ **NEVER skip preview** — MUST send preview image/GIF to chat before opening Bambu Studio. User must SEE the model.
- ❌ **NEVER skip Bambu Studio confirmation** — MUST open in BS, tell user to inspect, WAIT for explicit "looks good" / "print it"
- ❌ **NEVER auto-print** — No `bambu.py print` without user confirmation. AI models have errors.
- ❌ **NEVER skip model source choice** — MUST ask user: search vs generate vs not sure (default: search first)

### MUST Do These (in order)
1. **Collect info** → Ask model source, dimensions (if generate), colors, material
2. **Get model** → Search or generate per user choice
3. **Analyze** → `analyze.py --orient --repair` on every model
4. **Preview to chat** → `preview.py --views turntable` → **send image/GIF to user**
5. **Open Bambu Studio** → `open -a "BambuStudio" model.3mf` (or model.stl/obj)
6. **User slices in Bambu Studio** → Tell user to slice, inspect, and conf...

# 🖨️ Bambu Studio AI

Full-stack Bambu Lab 3D printing skill for [OpenClaw](https://github.com/openclaw/openclaw).

**Idea → Search/Generate → Analyze & Repair → Preview → Open Bambu Studio → User Slice & Confirm → Print → Monitor → Notify**

[![ClawHub](https://img.shields.io/badge/ClawHub-bambu--studio--ai-blue)](https://clawhub.ai/heyixuan2/bambu-studio-ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## Table of Contents

- [Features](#features)
- [Supported Printers](#supported-printers)
- [Model Requirements](#model-requirements)
- [Installation](#installation)
- [Setup](#setup)
- [The Full Pipeline](#the-full-pipeline)
- [Model Sourcing](#model-sourcing-search-vs-generate)
- [AI 3D Generation](#ai-3d-generation)
- [Model Analysis & Repair](#model-analysis--repair)
- [Print Monitoring](#print-monitoring)
- [Connection Modes](#connection-modes)
- [Configuration](#configuration)
- [Commands Reference](#commands-reference)
- [Material Guide](#material-guide)
- [Troubleshooting](#troubleshooting)
- [Project Structure](#project-structure)
- [Contributing](#contributing)

---

## Features

| Feature | Description |
|---------|-------------|
| 🔎 **Model Search** | Search Printables, MakerWorld, Thingiverse, Thangs for existing models |
| 🎨 **AI 3D Generation** | Text-to-3D and Image-to-3D via Meshy, Tripo3D, Printpal, or 3D AI Studio |
| 🎨 **Multi-Color AMS** | Auto-detect ≤8 colors from texture, vertex-color OBJ pipeline, salient-detail protection, tunable parameters |
| 🔆 **AI Shadow Handling** | Pixel-level HSV family classification bypasses baked lighting — no shadow removal needed |
| 🔍 **11-Point Analysis** | Printability check: walls, overhangs, tolerance, infill, layer height, floating parts |
| 🔧 **Auto Mesh Repair** | Fix non-manifold edges, holes, bad normals, tiered by severity |
| 📏 **Auto Orient & Scale** | Optimal print orientation, auto unit detection (m→mm) |
| 🔄 **Format Conversion** | Auto GLB→STL (si...