SETUP_GUIDE.sh

# ===========================================================
# AI 3D Model Generator — Complete Setup & Deployment Guide
# ===========================================================
#
# This file contains step-by-step instructions for deploying
# the pipeline to Hugging Face Spaces and connecting it to n8n.
#
# Table of Contents:
# 1. Overview
# 2. Hugging Face Space Deployment
# 3. n8n Workflow Setup
# 4. Testing the Pipeline
# 5. API Reference
# ===========================================================

# ===========================================================
# 1. OVERVIEW
# ===========================================================
#
# Pipeline Flow:
#
#   [n8n Webhook] ──▶ [Parse Request] ──▶ [Download Images]
#       │                                        │
#       ▼                                        ▼
#   [Receive POST with]              [Convert URLs to base64]
#   [images + prompt]                         │
#                                             ▼
#                          [Call HF Space Gradio API]
#                                  │
#                                  ▼
#                        [TripoSG Pipeline]
#                        ├─ Background Removal (RMBG-1.4)
#                        ├─ Best View Selection
#                        ├─ 3D Reconstruction
#                        ├─ Manifold Repair
#                        ├─ Dimension Scaling
#                        └─ (Optional) Part Segmentation
#                                  │
#                                  ▼
#                     [Download GLB/OBJ/STL File]
#                                  │
#                                  ▼
#                     [Respond with Binary File]
#
# ===========================================================


# ===========================================================
# 2. HUGGING FACE SPACE DEPLOYMENT
# ===========================================================

# Step 1: Create a new Hugging Face Space
# ----------------------------------------
# Go to: https://huggingface.co/new-space
# - Owner: your-username
# - Space name: ai-3d-generator
# - License: MIT
# - SDK: Gradio
# - Hardware: ZeroGPU (or GPU Basic for testing)
# - Click "Create Space"

# Step 2: Upload files via Git
# ----------------------------------------
# Clone your new space locally:

git clone https://huggingface.co/spaces/YOUR-USERNAME/ai-3d-generator
cd ai-3d-generator

# Copy all files from this directory:
cp /path/to/ai-3d-generation-print-ready/* .

# The following files should be in the space:
# ├── README.md          (HF Space config — already has YAML frontmatter)
# ├── app.py             (Main Gradio application)
# ├── mesh_utils.py      (Mesh processing utilities)
# ├── requirements.txt   (Python dependencies)
# └── workflow.json      (n8n workflow — for your reference, not needed in Space)

# Push to Hugging Face:
git add .
git commit -m "Initial deployment: AI 3D Model Generator"
git push

# Step 3: Configure HF Space secrets (optional)
# ----------------------------------------
# Go to your Space Settings → Variables and Secrets
# Add if using private models:
#   HF_TOKEN = hf_xxxxxxxxxxxxxxxxxxxxx

# Step 4: Wait for build
# ----------------------------------------
# The Space will automatically build and deploy.
# Watch the "Build" tab for progress (~5-10 minutes first time).
# Once running, your Space URL will be:
#   https://YOUR-USERNAME-ai-3d-generator.hf.space


# ===========================================================
# 3. N8N WORKFLOW SETUP
# ===========================================================

# Step 1: Import the workflow
# ----------------------------------------
# In n8n, go to: Workflows → Import from File
# Select: workflow.json from this directory
# The workflow will be imported with all nodes pre-configured.

# Step 2: Configure variables
# ----------------------------------------
# In n8n, go to: Settings → Variables
# Add these variables:
#
#   HF_SPACE_URL = YOUR-USERNAME-ai-3d-generator.hf.space
#   HF_TOKEN     = hf_xxxxxxxxxxxxxxxxxxxxx  (your HF access token)
#
# Alternatively, set up HuggingFace API credentials in n8n:
# Settings → Credentials → Add Credential → Hugging Face API

# Step 3: Activate the workflow
# ----------------------------------------
# Toggle the workflow to "Active"
# Note your webhook URL:
#   https://your-n8n-instance.com/webhook/generate-3d-model


# ===========================================================
# 4. TESTING THE PIPELINE
# ===========================================================

# Test via curl (images as URLs):
curl -X POST https://your-n8n-instance.com/webhook/generate-3d-model \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "https://example.com/front-view.jpg",
      "https://example.com/side-view.jpg",
      "https://example.com/back-view.jpg"
    ],
    "prompt": "Industrial bracket, base is 10cm x 5cm, M6 bolt holes on corners, matte steel finish",
    "faces": 50000,
    "format": "glb",
    "modular": false
  }' \
  --output model.glb

# Test via curl (images as base64):
IMAGE_B64=$(base64 -w0 my_photo.jpg)
curl -X POST https://your-n8n-instance.com/webhook/generate-3d-model \
  -H "Content-Type: application/json" \
  -d "{
    \"images\": [\"data:image/jpeg;base64,$IMAGE_B64\"],
    \"prompt\": \"Phone stand, height: 12cm, modern minimalist design\",
    \"faces\": 30000,
    \"format\": \"stl\"
  }" \
  --output model.stl

# Test via Python:
# import requests
# response = requests.post(
#     "https://your-n8n-instance.com/webhook/generate-3d-model",
#     json={
#         "images": ["https://example.com/object.jpg"],
#         "prompt": "Coffee mug, diameter: 8cm, height: 10cm",
#         "faces": 50000,
#         "format": "glb",
#     },
# )
# with open("model.glb", "wb") as f:
#     f.write(response.content)

# Test the HF Space directly (without n8n):
# Open your Space URL in a browser and use the web UI directly.


# ===========================================================
# 5. API REFERENCE
# ===========================================================

# Webhook Request Format:
# POST /webhook/generate-3d-model
# Content-Type: application/json
#
# {
#   "images": [                          // Array of image sources
#     "https://example.com/front.jpg",   // Image URLs (auto-downloaded)
#     "data:image/png;base64,iVBOR..."   // Or base64 encoded images
#   ],
#   "prompt": "string",                  // Text instructions
#                                        // Supports dimension extraction:
#                                        //   "base is 10cm"
#                                        //   "10cm x 5cm x 3cm"
#                                        //   "height: 200mm"
#                                        //   "scale 1:10"
#   "faces": 50000,                      // Target face count (5000-90000)
#   "format": "glb",                     // Export format: glb, obj, stl
#   "modular": false                     // Split into modular parts
# }
#
# Response:
# 200 OK — Binary file (GLB/OBJ/STL)
# Headers:
#   Content-Disposition: attachment; filename="model_20260224_120000.glb"
#   Content-Type: model/gltf-binary
#   X-Pipeline-Status: "✅ Complete in 45.2s — manifold: True, vertices: 12345, faces: 50000"
#
# Error Response:
# 500 Internal Server Error
# { "success": false, "error": "...", "message": "..." }

# ===========================================================
# SUPPORTED TEXT PROMPT PATTERNS
# ===========================================================
# The pipeline parses your text prompt to extract dimensions:
#
# Pattern                         Example
# ─────────────────────────────── ──────────────────────────────
# 3D dimensions:                  "10cm x 5cm x 3cm"
# Individual dims:                "base is 10cm", "height: 200mm"
# Scale ratios:                   "scale 1:10", "ratio is 1:5"
# Materials (passed to model):    "matte steel finish"
# Details (passed to model):      "M6 bolt holes on each corner"
# Style (passed to model):        "modern minimalist design"
#
# Units supported: mm, cm, m, in, inch, inches, ft, feet