README.md

---
license: apache-2.0
pipeline_tag: text-to-3d
library_name: transformers
---

# alpha3D-v1 🧊🎨

**alpha3D-v1** — это экспериментальная легковесная нейросеть для генерации 3D-объектов по текстовому описанию (Text-to-3D).

Модель преобразует текстовые эмбеддинги в цветные облака точек (Point Clouds). Обучена на синтетическом датасете геометрических примитивов.

✨ Возможности

    Генерация форм: Куб (Cube), Сфера (Sphere).
    Генерация цветов: Красный, Зеленый, Синий.
    Интерполяция: Умеет смешивать формы и цвета (например, фиолетовый кубо-шар).
    Формат: Выводит облако из 1000 точек (XYZ + RGB).

🛠 Установка

Для запуска вам понадобятся Python и несколько библиотек:

```Bash
pip install torch numpy matplotlib safetensors
```

🚀 Как запустить (Inference)

Если у вас уже есть файлы модели (model.safetensors, config.json, vocab.json), используйте этот код:

```Python
from safetensors.torch import load_file
import torch
import json
import numpy as np
import matplotlib.pyplot as plt

# 1. Загрузка конфига и словаря
with open("config.json", "r") as f: config = json.load(f)
with open("vocab.json", "r") as f: vocab = json.load(f)

# 2. Инициализация модели (Архитектура MLP)
model = torch.nn.Sequential(
    torch.nn.Linear(5, 128), torch.nn.BatchNorm1d(128), torch.nn.ReLU(),
    torch.nn.Linear(128, 512), torch.nn.BatchNorm1d(512), torch.nn.ReLU(),
    torch.nn.Linear(512, 1024), torch.nn.ReLU(),
    torch.nn.Linear(1024, config['parameters']['num_points'] * 6)
)

# 3. Загрузка весов
model.load_state_dict(load_file("model.safetensors"))
model.eval()

# 4. Функция генерации
def generate(color, shape):
    vec = [0.0] * 5
    if color in vocab: vec[vocab[color]] = 1.0
    if shape in vocab: vec[vocab[shape]] = 1.0
    
    with torch.no_grad():
        out = model(torch.tensor([vec])).numpy()[0]
    
    # Визуализация
    xyz, rgb = out.reshape(-1, 6)[:, :3], np.clip(out.reshape(-1, 6)[:, 3:], 0, 1)
    fig = plt.figure(); ax = fig.add_subplot(111, projection='3d')
    ax.scatter(xyz[:,0], xyz[:,1], xyz[:,2], c=rgb, s=10)
    plt.show()

# 🔥 Запуск
generate("red", "sphere")
generate("blue", "cube")
```
🧠 Архитектура и Обучение

Модель представляет собой простой MLP (Multi-Layer Perceptron):

    Вход: One-Hot вектор размерностью 5 (словарь: red, green, blue, cube, sphere).
    Скрытые слои: 128 -> 512 -> 1024 нейронов.
    Выход: Вектор размерностью 6000 (1000 точек × 6 значений: X, Y, Z, R, G, B).
    Функция потерь: MSE (Mean Squared Error).
    Датасет: Синтетический генератор. Сферы создаются по спирали Фибоначчи, кубы — по равномерной сетке.

🔮 Латетное пространство

Модель способна на морфинг между объектами. Смешивая входные векторы, можно получать промежуточные состояния:

    0.5 * Cube + 0.5 * Sphere = Раздутый куб ("Подушечка").
    0.5 * Red + 0.5 * Blue = Фиолетовый (Magenta).

📄 Лицензия

Распространяется под лицензией Apache 2.0. Вы можете использовать, модифицировать и распространять этот код, в том числе в коммерческих целях.