ImaForm

ImaForm is a hybrid generative CAD system that supports two distinct workflows:

1. Photo + Sentence Mode: Generate 3D printable holders/mounts/cases from user photos and natural language
2. Vibe-CAD Mode: Engineer-oriented command-first editing for fixtures (trays, plates, brackets, covers)

Both workflows share common backend infrastructure including a unified SDF/voxel geometry engine, validation services, and export functionality.

Tech Stack

Frontend

• Framework: Next.js 14+ (App Router)
• Language: TypeScript 5.0+
• Styling: Tailwind CSS + shadcn/ui
• 3D Visualization: Three.js + React Three Fiber
• State Management: Zustand
• Forms: React Hook Form + Zod

Backend

• Framework: FastAPI 0.104+
• Language: Python 3.11-3.12
• ASGI Server: Uvicorn 0.24+
• Package Manager: uv (with uv.lock) or pip (with requirements.txt)
• Task Queue: Celery 5.3+ + Redis 7.0+
• Database: PostgreSQL 16+ + SQLAlchemy 2.0 (async)

AI/ML

• Image Processing: OpenCV 4.8+ (RANSAC-based segmentation)
• NLP: Hugging Face Transformers 4.35+ (BERT)
• Geometry Engine: PyTorch 2.1+ + Taichi 1.7+ (Hybrid SDF/voxel runtime)

DevOps

• Containerization: Docker + Docker Compose
• Reverse Proxy: Nginx
• CI/CD: GitHub Actions

Project Structure

imaform/
├── frontend/           # Next.js frontend application
├── backend/            # FastAPI backend services
├── geometry/            # SDF/voxel geometry engine
├── storage/            # File storage (uploads, exports, cache)
├── docker/             # Docker configurations
├── scripts/            # Utility scripts
├── docs/               # Documentation
└── README.md           # This file

Getting Started

Prerequisites

• Node.js 20+
• Python 3.11-3.12 (3.13+ not supported - Depth Anything v3 requires numpy<2)
• Docker & Docker Compose
• NVIDIA GPU (optional, for GPU acceleration)

Quick Start with Docker

The fastest way to get started is using Docker:

# 1. Clone repository
git clone <repository-url>
cd imaform

# 2. Configure environment
cp docker/.env.example docker/.env
# Edit docker/.env with your configuration

# 3. Build Docker images
./scripts/docker/build.sh

# 4. Start all containers
./scripts/docker/up.sh

# 5. Wait for services to be ready
./scripts/docker/wait-for-services.sh

# 6. Check health
./scripts/docker/health-check.sh

Access the application:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Nginx: http://localhost:80

Docker Development

For development with hot reload:

# Start development containers
./scripts/dev/docker/dev-up.sh

# Rebuild specific service
./scripts/dev/docker/rebuild.sh --service backend

# Stop development containers
./scripts/dev/docker/dev-down.sh

Docker Production

For production deployment:

# Start production containers
./scripts/deploy/docker/prod-up.sh

# Backup data
./scripts/deploy/docker/backup.sh --type all

# Stop production containers
./scripts/deploy/docker/prod-down.sh

Docker Management

# View logs
./scripts/docker/logs.sh --follow

# Check health
./scripts/docker/health-check.sh

# Stop all containers
./scripts/docker/down.sh

# Clean up (remove containers, volumes, images)
./scripts/docker/clean.sh --volumes --images --cache

Manual Setup

Frontend

cd frontend
npm install
npm run dev

Backend

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

Geometry Engine

cd geometry
pip install -e .
python -m imaform_geometry.server

Documentation

• Architecture
• API Reference
• User Guide
• Docker Setup Guide
• Docker Compose Configuration
• Production Deployment Guide
• Troubleshooting Guide

License

[License information]