# FormaAi Studio: Unified 3D Neural Generation Pipeline

[English version](#english-version) | [Русская версия](#русская-версия)

---
## Лицензия и авторство / License and Attribution

**Русский:**
Этот проект основан на архитектуре [TRELLIS](https://github.com/microsoft/TRELLIS), разработанной Microsoft. Исходный код, предоставленный Microsoft, распространяется на условиях лицензии [MIT](https://github.com/microsoft/TRELLIS/blob/main/LICENSE).
Все остальные компоненты, скрипты и изменения, созданные в рамках проекта *FormaAI*, распространяются под лицензией [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/). Использование проекта *FormaAI* в коммерческих целях строго запрещено.

**English:**
This project is based on the [TRELLIS](https://github.com/microsoft/TRELLIS) architecture developed by Microsoft. The original code provided by Microsoft is licensed under the [MIT License](https://github.com/microsoft/TRELLIS/blob/main/LICENSE).
All other components, scripts, and modifications created for *FormaAI* are licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/). Commercial use of the *FormaAI* project is strictly prohibited.

---

## English Version

FormaAi is a unified hybrid 3D neural generation framework. It consolidates fast feed-forward generation, discrete 3D Gaussian Splatting representation, and continuous NeRF fields into a single, cohesive neural pipeline. Built on top of Microsoft's TRELLIS framework, it allows users to convert a single 2D image into high-fidelity textured 3D assets (GLB, PLY point clouds, and a compatible OBJ zip package) in seconds.

### Technical Architecture
The pipeline consists of the following processing stages:
1. **Preprocessing (Rembg)**: Background removal and image centering/resizing to a clean $518 \times 518$ RGB template.
2. **Stage 1 (Sparse Structure Flow Matching)**: Generates a sparse 3D occupancy lattice representing the coarse structure.
3. **Stage 2 (Structured Latent Flow Matching)**: Synthesizes structured latents corresponding to the object features.
4. **Model Offloading Decoders**: Decodes the structured latent into representation-specific formats (Mesh, Gaussians, Radiance Fields) sequentially on the GPU, offloading each to CPU memory immediately after to maintain a very low VRAM footprint.
5. **AI Texture Upscaling (Swin2SR)**: Uses Swin2SR models to upscale baked textures from $1024 \times 1024$ to 2K or 4K resolution dynamically. Includes an intelligent GPU OOM auto-fallback to CPU.

---

### Local Installation Guide

#### 1. System Requirements
- **OS**: Linux (Ubuntu 20.04+ recommended)
- **GPU**: NVIDIA GPU with CUDA support (Minimum: **8 GB VRAM** for RTX 3060/4060; Recommended: **12+ GB VRAM**).
- **RAM**: 16 GB minimum (32 GB recommended for x4 texture upscaling).

#### 2. Virtual Environment Setup
Ensure Python 3.10 and virtualenv are installed. Create and activate the environment:
```bash
# Inside the project root folder
python3.10 -m venv TRELLIS-main/venv_trellis
source TRELLIS-main/venv_trellis/bin/source/activate
```

#### 3. Installing Dependencies
Install core dependencies, PyTorch, and specific CUDA sub-modules:
```bash
# 1. Install standard requirements
./TRELLIS-main/venv_trellis/bin/pip install -r requirements.txt

# 2. Install specialized CUDA packages (e.g. spconv, diff-gaussian-rasterization, xformers)
# Ensure CUDA_HOME is set if compiling from source:
export CUDA_HOME=/usr/local/cuda
./TRELLIS-main/venv_trellis/bin/pip install spconv-cu121
./TRELLIS-main/venv_trellis/bin/pip install xformers --index-url https://download.pytorch.org/whl/cu121

# Install diff-gaussian-rasterization
./TRELLIS-main/venv_trellis/bin/pip install "git+https://github.com/graphdeco-inria/diff-gaussian-rasterization.git"
```

#### 4. How to Start the Web UI
Run the FastAPI backend server using the virtual environment:
```bash
./TRELLIS-main/venv_trellis/bin/python -m uvicorn server:app --host 127.0.0.1 --port 7860
```
Open [http://127.0.0.1:7860](http://127.0.0.1:7860) in your web browser.

#### 5. How to Run Standalone Tests
Execute the console verification script:
```bash
./TRELLIS-main/venv_trellis/bin/python test_formaai.py
```

---

## Русская Версия

**FormaAi** — это унифицированная гибридная нейросетевая среда генерации 3D-объектов. Она объединяет быструю генерацию методом прямого прохода (feed-forward), дискретное представление 3D Gaussian Splatting и непрерывные поля излучения (NeRF) в единый пайплайн. Созданный на базе SOTA-фреймворка TRELLIS от Microsoft, FormaAi преобразует одно 2D-изображение в высокодетализированный 3D-ассет (GLB-меш, PLY-облако точек и OBJ-пакет в архиве) за несколько секунд.

### Техническая Архитектура
Пайплайн состоит из следующих вычислительных этапов:
1. **Препроцессинг (Rembg)**: Автоматическое вырезание фона, центрирование и масштабирование картинки под шаблон $518 \times 518$ RGB.
2. **Этап 1 (Sparse Structure Flow Matching)**: Генерация разреженной пространственной решетки заполнения, описывающей грубую форму объекта.
3. **Этап 2 (Structured Latent Flow Matching)**: Синтез структурированного латентного представления для детальных признаков.
4. **Модульная выгрузка декодеров (Model Offloading)**: Декодирование латентов в Меш, Облако Гауссианов и Поле излучения происходит на GPU последовательно. Сразу после работы каждый декодер выгружается в ОЗУ (на CPU), что снижает пиковое потребление видеопамяти.
5. **AI-масштабирование текстур (Swin2SR)**: Использование Swin2SR для апскейлинга текстуры с базовых $1024 \times 1024$ до 2K/4K разрешения. Имеет систему автоматического перенаправления вычислений на CPU при нехватке VRAM (OOM).

---

### Инструкция по локальному запуску

#### 1. Системные требования
- **ОС**: Linux (рекомендуется Ubuntu 20.04+)
- **GPU**: Видеокарта NVIDIA с поддержкой CUDA (Минимум: **8 ГБ VRAM**; Рекомендуется: **12+ ГБ VRAM**).
- **ОЗУ**: Минимум 16 ГБ RAM (рекомендуется 32 ГБ для текстур 4K).

#### 2. Настройка виртуального окружения
Убедитесь, что установлены Python 3.10 и пакет venv. Создайте и активируйте окружение:
```bash
# В корневой папке проекта
python3.10 -m venv TRELLIS-main/venv_trellis
source TRELLIS-main/venv_trellis/bin/activate
```

#### 3. Установка зависимостей
Установите основные зависимости, PyTorch и специализированные CUDA-библиотеки:
```bash
# 1. Установка стандартных требований
./TRELLIS-main/venv_trellis/bin/pip install -r requirements.txt

# 2. Установка специализированных CUDA-пакетов
export CUDA_HOME=/usr/local/cuda
./TRELLIS-main/venv_trellis/bin/pip install spconv-cu121
./TRELLIS-main/venv_trellis/bin/pip install xformers --index-url https://download.pytorch.org/whl/cu121

# Установка растеризатора Гауссианов
./TRELLIS-main/venv_trellis/bin/pip install "git+https://github.com/graphdeco-inria/diff-gaussian-rasterization.git"
```

#### 4. Как запустить веб-интерфейс
Запустите FastAPI backend-сервер из виртуального окружения:
```bash
./TRELLIS-main/venv_trellis/bin/python -m uvicorn server:app --host 127.0.0.1 --port 7860
```
Откройте [http://127.0.0.1:7860](http://127.0.0.1:7860) в вашем браузере.

#### 5. Как запустить консольный тест
Запустите скрипт проверки в терминале:
```bash
./TRELLIS-main/venv_trellis/bin/python test_formaai.py
```