# Blender Pipeline — Figma → PatternGen → 3D Compositing

> Полный конвейер от Figma-дизайна до 3D-compositing в Blender.
> Основано на [patterngen-oss](https://github.com/halfof8/patterngen-oss) workflow.

## Обзор

```
Figma (artboard 1920×1080)
    ↓ Plugin "PatternGen Scene Export"
Scene JSON (titles as 2× PNG data URLs + colors + seed)
    ↓ Load в PatternGen web app
Procedural pattern generation (Canvas 2D)
    ↓ EXPORT (JSZip + FileSaver)
ZIP: scene_titles/*.png, scene_patterns/*.png, scene_dots/*.png
    ↓ Blender addon "PatternGen Importer"
3 emissive planes с alpha-blending → Cycles/Eevee render
```

---

## Этап 1: Figma → Scene JSON

### Подготовка артборда

- Frame размер: **1920×1080 px** (Full HD)
- Grid: **20 px** (Layout Grid → Grid → 20 px)
- Каждый title — top-level child frame, размеры кратны 20
- Название фрейма = `sceneName` (префикс для экспорта)
- Цвета: любые (плагин сканирует fills/strokes)

### Экспорт

1. Выбрать один или несколько фреймов 1920×1080
2. **Plugins → Development → PatternGen Scene Export**
3. **Export Selected Frames**
4. Результат: `<frameName>_patterngen.json`

### Структура JSON

```json
{
  "sceneName": "My Title",
  "seed": 123456789,          // 31-bit integer, determinism
  "colors": ["#FF0000", "#00FF00", "#0000FF"],  // detected colors
  "titles": [
    {
      "id": "title_1",
      "x": 100,                // snapped to 20px grid
      "y": 200,
      "w": 400,
      "h": 100,
      "img": "data:image/png;base64,..."  // 2× retina PNG
    }
  ],
  "defaults": {
    "durationMs": 6000,
    "density": 10,
    "proximity": 2,
    "stagger": 3,
    "theme": "dark"
  }
}
```

### Что экспортируется

- **Titles**: 2× PNG (retina), data URL, позиции snapped к сетке
- **Color set**: уникальные цвета fills/strokes (кроме #000 и #FFF)
- **Seed**: 31-bit integer — детерминированная генерация паттернов
- **Scene defaults**: продолжительность, плотность, proximity, stagger, тема

---

## Этап 2: PatternGen Web App

### Загрузка

1. Открыть PatternGen (localhost:5173)
2. Кнопка **LOAD** → выбрать `*_patterngen.json`
3. Паттерны генерируются **детерминированно по seed**
4. Сцена сразу готова к **PLAY**

### Ручное редактирование

- **Drag & Drop** PNG/JPG изображений на canvas (snap to 20 px grid)
- **Drag** для перемещения, drag off canvas для удаления
- **+ ADD COLOR** — до 3 кастомных цветов (color picker)
- Клик по swatch — toggle on/off

### Параметры

| Параметр     | Диапазон | Описание |
|-------------|---------|----------|
| **Density** | 1–20    | Количество паттерн-элементов |
| **Proximity** | 1–20  | Минимальное расстояние от titles |
| **Stagger** | 0–5     | Разброс animation delay |
| **Grid** | toggle | 20 px reference grid |
| **Theme** | dark/light | UI theme |

---

## Этап 3: Экспорт PNG-секвенций

### Формат ZIP

```
scene_pattern_gen.zip
├── titles/
│   scene_titles_00000.png
│   scene_titles_000001.png
│   ...
├── patterns/
│   scene_patterns_00000.png
│   ...
└── dots/
    scene_dots_00000.png
    ...
```

### Параметры экспорта

- **Scale**: 4× (EXPORT_SCALE = 4 → 7680×4320px)
- **FPS**: 24
- **Фон**: прозрачный (RGBA)
- **Слои**: 3 отдельных (titles, patterns, dots)

### Фазы рендера

```
titles:     durationMs (1×) — plays once
patterns:   durationMs (1×) — plays once
dots:       4000ms loop — infinite loop
```

### Easing при экспорте

Выбирается один из 7 типов:
`linear`, `easeIn`, `easeOut`, `easeInOut`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`

---

## Этап 4: Blender Import

### Установка

1. Blender → **Edit → Preferences → Add-ons → Install…**
2. Выбрать `patterngen_importer.py`
3. Поставить галочку для активации
4. Открыть N-panel → вкладка **PatternGen**

### Импорт сцены

1. Установить **Scene Folder** на распакованную папку
2. Кнопка **Import Scene Folders**
3. Три planes создаются в origin

### Конфигурация слоёв

| Layer | Cyclic | Location (m) | Rotation | Scale |
|-------|--------|-------------|----------|-------|
| titles | off | (0, 0, 0) | 90° на X | 6×6×6 |
| patterns | off | (0, 0.1, 0) | 90° на X | 6×6×6 |
| dots | **on** | (0, 0.2, 0) | 90° на X | 6×6×6 |

### Node Tree материалов

```
Image Texture (SEQUENCE, auto-refresh ON)
  Color ─┬─► Principled BSDF › Base Color
         └─► Principled BSDF › Emission Color (strength = 1)
  Alpha ───► Principled BSDF › Alpha
```

### Image Sequence настройки

- **Start Frame**: 0
- **Frames**: количество PNG в папке
- **Offset**: 0
- **Auto Refresh**: ON
- **Cyclic**: ON для `dots`, OFF для `titles`/`patterns`

### Sync Start Frame

1. Выбрать plane(s) (Shift+click или A для всех)
2. В секции **Sync Start Frame** ввести новое значение
3. **Apply to Selected** — все image-sequence текстуры обновлены

### Замечания

- **Blend Method**: `BLEND` (alpha renders clean в Eevee/Cycles)
- При артефактах сортировки переключить на `HASHED`
- Повторный импорт создаёт дубликаты (`.001`, `.002`) — удалить вручную
- Отступ 0.1m между слоями — только для предотвращения z-fighting
- Plane scale настроен по aspect ratio изображения (16:9)

---

## Полный конвейер в цифрах

| Параметр | Значение |
|----------|---------|
| Canvas | 1920×1080 |
| Export Scale | 4× (7680×4320) |
| FPS | 24 |
| Grid | 20 px |
| Duration | 6000ms (default) |
| Dots Loop | 4000ms |
| Cycle | 4× duration = 24s |
| Patterns | 7 animation types |
| Colors | 2 fixed + 3 custom max |
| Export Layers | 3 (titles, patterns, dots) |

---

## Референсы кода

- `figma-plugin/README.md` — Figma plugin setup, export format
- `blender-addon/README.md` — Blender addon installation, node tree
- `src/export/exporter.ts` — PNG sequence export, JSZip, FileSaver
- `src/engine/timeline.ts` — Phase 1/2/3 timing, dots loop
- `src/types.ts` — CANVAS_W/H, EXPORT_SCALE, FPS, GRID_SIZE