1. Create an account at huggingface.co
2. Accept the model licenses (required!):
   • TRELLIS 2 License - Click "Agree and access"
   • PartPacker License - If using PartPacker
3. Create an access token:
   • Go to Settings → Access Tokens
   • Create a new token with Read permissions
   • Save this token, you'll need it later

1. Sign up at modal.com
2. You get $30 free credits - enough for ~100+ generations
3. Install Modal CLI:

   pip install modal
   modal setup  # Follow the authentication flow
   

• Python 3.10+
• Node.js 18+ (for frontend)
• Git

# Clone the repository
git clone https://github.com/sciences44/meshii.git
cd meshii

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env and add your HF_TOKEN

# Add HuggingFace token to Modal
modal secret create huggingface-secret HF_TOKEN="hf_your_token_here"

# Download model weights (takes 10-20 minutes)
modal run backend/modal_app.py::download_models

# Deploy to Modal
modal deploy backend/modal_app.py
# Note the URL: https://YOUR_USERNAME--meshii-fastapi-app.modal.run

# Update .env with your Modal URL
# VITE_API_URL=https://YOUR_USERNAME--meshii-fastapi-app.modal.run

# Setup frontend
cd frontend
npm install
npm run dev

# In another terminal: Start local post-processing server (optional)
# Required for mesh optimization (decimation, tris-to-quads, etc.)
cd backend
uvicorn local_postprocess:app --host 0.0.0.0 --port 8001

# Full setup wizard
python setup.py setup

# Check prerequisites
python setup.py check

# Deploy to Modal
python setup.py deploy

# Download model weights
python setup.py download

# Run Modal in dev mode (hot reload)
python setup.py serve

# Start frontend only
python setup.py frontend

# Start local post-processing server (optional)
cd backend && uvicorn local_postprocess:app --host 0.0.0.0 --port 8001

Post-Processing Server: This optional local server handles advanced mesh optimization (decimation, tris-to-quads, topology fixes). It runs on localhost:8001 and uses pymeshlab for processing. Only needed if you want to use these features.

API

import httpx
import os

# Get your Modal API URL from environment or use your deployment URL
API_URL = os.getenv("VITE_API_URL", "https://YOUR_USERNAME--meshii-fastapi-app.modal.run")

with open("input.png", "rb") as f:
    response = httpx.post(
        f"{API_URL}/generate",
        files={"image": f},
        data={
            "model": "trellis2",
            "pipeline_type": "1024_cascade",
        },
    )

result = response.json()
# Download GLB from result['assets'][0]['url']

┌─────────────────┐         ┌─────────────────────────────────────────┐
│    Frontend     │         │              Modal (GPU Cloud)          │
│   (React/Vite)  │         │                                         │
│                 │◄────────┤  FastAPI Web App                        │
│  localhost:5173 │  HTTPS  │  ↳ /api/v1/generate                     │
│                 │ ──────► │  ↳ /api/v1/jobs                         │
│                 │         │  ↳ /api/v1/download                     │
└─────────────────┘         │                                         │
                            │  GPU Inference Classes:                 │
                            │  ├─ Trellis2Inference (A10G/A100)       │
                            │  ├─ TrellisInference (A100)             │
                            │  └─ PartPackerInference (L40S)          │
                            │                                         │
                            │  Modal Volumes:                         │
                            │  ├─ /models (HuggingFace weights)       │
                            │  └─ /results (Generated GLB files)      │
                            └─────────────────────────────────────────┘

Project Structure

meshii/
├── setup.py              # CLI setup tool
├── backend/
│   ├── modal_app.py      # Modal deployment & GPU inference
│   ├── config/           # Configuration management (Pydantic)
│   ├── strategies/       # Model inference strategies
│   ├── processors/       # Post-processing pipelines
│   ├── factories/        # Factory pattern for models
│   └── api/              # FastAPI routes
├── frontend/             # React + TypeScript UI
│   ├── src/components/   # UI components
│   ├── src/store/        # Zustand state management
│   └── src/hooks/        # Custom React hooks
└── configs/              # YAML presets
    ├── trellis2_*.yaml   # TRELLIS 2 presets
    ├── game_ready.yaml   # Game optimization
    └── print_ready.yaml  # 3D printing optimization

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: pytest tests/
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

Development Mode

# Run Modal with hot reload
modal serve backend/modal_app.py

# Run frontend with hot reload
cd frontend && npm run dev