# Visual Data Tools — Исследование инструментов для визуализации данных

> Дата: 2026-06-24
> Автор: neo

---

## Сводка

Исследование лучших инструментов для генерации блок-схем, mindmap, DRAKON-диаграмм и других типов диаграмм. Цель — найти оптимальный рабочий процесс для быстрой и точной генерации диаграмм в проекте.

---

## 1. Диаграммы как код (Diagrams as Code)

### 1.1 D2 (Diagram as Code)
- **Язык**: Собственный DSL (D2)
- **Рендер**: CLI → SVG, PNG, PDF
- **Плюсы**: 
  - Лучший визуальный результат «из коробки»
  - Автоматическая топологическая раскладка
  - Переменные, функции, итерации (можно генерировать из Python)
  - Маркеры на стрелках, поддержка анимации
  - Простой читаемый синтаксис
- **Минусы**: Меньше сообщество чем у Mermaid
- **Использование**: Блок-схемы, архитектуры, DRAKON-подобные диаграммы, flowcharts
- **Установка**: `brew install d2-lang` или с [GitHub](https://github.com/d2lang/d2)

**Пример D2:**
```d2
# diagram.d2
x: {
  A -> B -> C
  B -> D
}
```

---

### 1.2 Mermaid
- **Язык**: Markdown-like (встраивается в .md, .txt)
- **Рендер**: Встроен в GitHub, GitLab, Notion; CLI `@mermaid-js/mermaid-cli` → PNG/SVG
- **Плюсы**:
  - Встроен в GitHub/GitLab/Notion (без рендеринга)
  - Огромное сообщество
  - Поддержка: flowchart, state diagram, sequence, Gantt, ER-diagram
- **Минусы**: 
  - Визуально посредственно
  - Ограниченный контроль позиционирования
  - Сложно кастомизировать цвета/шрифты
- **Использование**: Документация в Markdown, GitHub-репозитории

**Пример Mermaid:**
```mermaid
flowchart LR
    A[Старт] --> B[Процесс]
    B --> C{Решение}
    C -->|Да| D[Действие]
    C -->|Нет| E[Результат]
```

---

### 1.3 PlantUML
- **Язык**: UML-синтаксис
- **Рендер**: CLI → SVG, PNG
- **Плюсы**: Зрелый, поддержка UML, BPMN, много тем
- **Минусы**: Медленный рендер, устаревший синтаксис
- **Использование**: UML-диаграммы, sequence diagrams

---

### 1.4 Graphviz (DOT)
- **Язык**: DOT DSL
- **Рендер**: CLI → SVG, PNG, PDF
- **Плюсы**: Мощная автоматическая раскладка для сложных графов
- **Минусы**: Непрозрачный синтаксис, трудно контролировать внешний вид
- **Использование**: Сложные графы, деревья, сетевые диаграммы

---

## 2. Mindmaps

### 2.1 markmap (РЕКОМЕНДУЕТСЯ)
- **Язык**: Markdown (иерархия через заголовки/списки)
- **Вывод**: Интерактивный HTML/JS
- **Плюсы**:
  - Встроен в VS Code (расширение)
  - CLI: `npx markmap mindmap.md -o mindmap.html`
  - Полностью интерактивный (зум, сворачивание)
  - Легко генерировать из Python
  - Красивый современный дизайн
- **Минусы**: Только markdown-вход (не визуальный редактор)
- **Использование**: Быстрые mindmaps из markdown, документация

**Пример markmap-входа:**
```markdown
# Mindmap
## Главный узел
### Подузел 1
- Ветвь 1.1
- Ветвь 1.2
### Подузел 2
```

---

### 2.2 Другие варианты mindmaps
- **Excalidraw** — визуальный редактор, «hand-drawn» стиль, идеален для набросков
- **XMind** — десктопное приложение, визуальный редактор
- **FreePlane** — open-source, мощный, но устаревший UI

---

## 3. Визуальные редакторы

### 3.1 Excalidraw
- **Тип**: Визуальный, «hand-drawn» стиль
- **Плюсы**: Быстрые наброски, drag-and-drop, коллаборация
- **Минусы**: Нет автоматической раскладки, ручной layout
- **Использование**: Быстрые обсуждения, дизайн, sketching

### 3.2 draw.io / diagrams.net
- **Тип**: Визуальный, drag-and-drop
- **Плюсы**: Много шаблонов, экспорт в SVG/PNG, интеграция с Google Docs/Confluence
- **Минусы**: Нет автоматической раскладки
- **Использование**: Классические блок-схемы, UML, архитектуры

### 3.3 tldraw
- **Тип**: React-компонент, визуальный
- **Плюсы**: Интерактивный, collaboration, drag-and-drop
- **Минусы**: Требует фронтенд-проект
- **Использование**: Встроенные визуальные редакторы в веб-приложениях

---

## 4. Специализированные инструменты

| Тип | Инструмент | Зачем |
|---|---|---|
| Architecture | Structurizr (C4 model) | Документация архитектуры из кода |
| Architecture | diagrams (Python) | Python → диаграммы инфраструктуры (AWS, GCP) |
| Sequence | Mermaid / D2 / PlantUML | API flows, взаимодействие сервисов |
| Network | Graphviz | Сетевая топология, графы зависимостей |
| Data viz | ECharts | Интерактивные дашборды с графиками |
| Data viz | D3.js | Кастомная интерактивная визуализация |
| DRAKON | SVG вручную | Полный контроль над дизайном, анимация, glow |

---

## 5. Рекомендованный рабочий процесс

```
Быстрые наброски          → Excalidraw (визуальный, скетчи)
    ↓
Mindmaps                 → markmap (markdown → интерактивный HTML)
    ↓
Блок-схемы/архитектура   → D2 (красивый CLI, переменные, итерации)
    ↓
В Markdown               → Mermaid (встроен в GitHub/GitLab)
    ↓
Pixel-perfect дизайн      → SVG вручную (как dracon.html)
```

---

## 6. Примеры генерации из Python

### 6.1 Mindmap через markmap

```python
import subprocess

# Создаём markdown
mindmap = """
# Проект
## Backend
### API
### Database
### Auth
## Frontend
### React
### CSS
"""

with open("mindmap.md", "w") as f:
    f.write(mindmap)

# Рендерим
subprocess.run(["npx", "-y", "markmap-cli", "mindmap.md", "-o", "mindmap.html"])
```

### 6.2 Блок-схема через D2

```python
import subprocess

d2_content = """
x: {
  shape: process
  A -> B -> C
  B -> D
}
"""

with open("diagram.d2", "w") as f:
    f.write(d2_content)

# Рендерим в SVG
subprocess.run(["d2", "diagram.d2", "output.svg"])
```

### 6.3 Mermaid из Python

```python
import subprocess

mermaid = """flowchart LR
    A[Старт] --> B[Процесс]
    B --> C{Решение}
    C -->|Да| D[Действие]
    C -->|Нет| E[Конец]
"""

with open("diagram.mmd", "w") as f:
    f.write(mermaid)

subprocess.run(["npx", "-y", "@mermaid-js/mermaid-cli", "diagram.mmd", "-o", "output.png"])
```

---

## 7. Сравнительная таблица

| Критерий | D2 | Mermaid | PlantUML | Graphviz | markmap | Excalidraw |
|---|---|---|---|---|---|---|
| **Визуал «из коробки»** | ★★★★★ | ★★★ | ★★★ | ★★ | ★★★★ | ★★★ |
| **Скорость создания** | ★★★★ | ★★★★★ | ★★★ | ★★ | ★★★★★ | ★★★★★ |
| **Контроль дизайна** | ★★★ | ★★ | ★★ | ★★ | ★★★ | ★★★★ |
| **Генерация из кода** | ★★★★ | ★★★ | ★★★ | ★★★★ | ★★★★ | ★★ |
| **Встраивание в Markdown** | ★★ | ★★★★★ | ★★ | ★★ | ★★★ | ★★ |
| **Интерактивность** | ★★ | ★★ | ★★ | ★★ | ★★★★★ | ★★★★ |
| **Сообщество** | ★★★ | ★★★★★ | ★★★★ | ★★★★ | ★★★ | ★★★★ |

---

## 8. Итоговые рекомендации

### Для твоих задач (ROI24, wow-design, автоматизация):

1. **Блок-схемы процессов** — D2 (CLI, переменные, итерации) или SVG вручную (pixel-perfect)
2. **Mindmaps для планирования** — markmap (markdown → интерактивный HTML)
3. **Архитектура сервисов** — D2 или diagrams (Python)
4. **Быстрые наброски** — Excalidraw
5. **Документация в Gitea** — Mermaid (если Gitea поддерживает) или встроенный SVG

### Рекомендуемый стек:
- **D2** для блок-схем
- **markmap** для mindmaps
- **SVG вручную** для pixel-perfect дизайна
- **Python subprocess** как glue-код для генерации

---

*Источники: D2 (github.com/d2lang/d2), markmap (github.com/markmap/markmap), Mermaid (mermaid.js.org), PlantUML (plantuml.com), Graphviz (graphviz.org), Excalidraw (excalidraw.com)*