commit 68b917401a556c929679858dd300b6ade8dbfd3f Author: neo Date: Wed Jun 24 14:37:40 2026 +0500 Initial commit: visual data tools research diff --git a/README.md b/README.md new file mode 100644 index 0000000..193bcae --- /dev/null +++ b/README.md @@ -0,0 +1,265 @@ +# 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)* diff --git a/examples.md b/examples.md new file mode 100644 index 0000000..2ac8786 --- /dev/null +++ b/examples.md @@ -0,0 +1,273 @@ +# Примеры диаграмм для визуального сравнения + +## D2 — Блок-схема процесса + +```d2 +# workflow.d2 +{ + edgeStyle: round + Start: { shape: circle } + + Start -> Briefing + Briefing -> Audit + Audit -> Question + + Question -> Create: Да + Question -> Clarify: Нет + + Create -> Approval + Clarify -> Approval: возврат + + Approval -> End + End: { shape: circle } +} +``` + +--- + +## Mermaid — Sequence Diagram + +```mermaid +sequenceDiagram + participant Client + participant API + participant DB + + Client->>API: POST /process + API->>DB: save data + DB-->>API: ok + API->>Client: 200 OK +``` + +--- + +## Mermaid — Flowchart + +```mermaid +flowchart TD + A[Старт] --> B[Брифинг клиента] + B --> C[Аудит процессов] + C --> D{Процессы
прозрачны?} + D -->|Да| E[Создание
DRAKON-схем] + D -->|Нет| F[Уточняем
процесс] + F -->|возврат| G[Согласование] + E --> G + G --> H[Готово] +``` + +--- + +## markmap — Mindmap + +```markdown +# Визуализация данных +## Блок-схемы +### D2 +- CLI-рендер +- Переменные +- Итерации +### Mermaid +- Markdown +- GitHub/GitLab +### SVG вручную +- Полный контроль +- Анимация +## Mindmaps +### markmap +- Markdown-вход +- Интерактивный +- VS Code +## Архитектура +### diagrams (Python) +- AWS/GCP +- Network +### Structurizr +- C4 model +``` + +--- + +## PlantUML — Component Diagram + +```plantuml +@startuml +component "API Server" as api +component "Database" as db +component "Cache" as cache + +api --> db +api --> cache +@enduml +``` + +--- + +## Graphviz — Network Diagram + +```dot +digraph network { + rankdir=LR + node [shape=box, style=filled, fillcolor="#16162a", fontcolor=white] + + client [label="Client"] + api [label="API Server"] + db [label="Database"] + cache [label="Redis Cache"] + + client -> api + api -> db + api -> cache + cache -> db +} +``` + +--- + +## D2 — Architecture Diagram + +```d2 +{ + edgeStyle: round + + User: { shape: person } + + User -> Web App + User -> Mobile App + + Web App -> API + Mobile App -> API + + API -> Auth Service + API -> Data Service + + Data Service -> PostgreSQL + Data Service -> Redis + Data Service -> S3 +} +``` + +--- + +## D2 — DRAKON-подобная схема + +```d2 +{ + edgeStyle: round + edgeStyle.curve: smooth + + {dir: down} + Start -> Briefing + Briefing -> Audit + Audit -> Question + Question -> Create + Question -> Clarify + Clarify -> Approval + Create -> Approval + Approval -> End +} + +Start: { + text: Старт +} + +Briefing: { + text: "Брифинг\nклиента" +} + +Audit: { + text: "Аудит\nпроцессов" +} + +Question: { + text: "Процессы\nпрозрачны?" +} + +Create: { + text: "Создание\nDRAKON-схем" +} + +Clarify: { + text: "Уточняем\nпроцесс" +} + +Approval: { + text: "Согласование" +} + +End: { + text: "Готово" +} +``` + +--- + +## SVG — DRAKON-схема (встраиваемая) + +См. `dracon.html` в проекте `dracon-tldraw` — полная DRAKON-схема с glow-эффектами и анимациями. + +--- + +## Python — Генерация из кода + +### D2 из Python + +```python +#!/usr/bin/env python3 +"""Генерация блок-схемы из Python-конфига.""" + +import subprocess +import json + +# Конфиг процесса +process = { + "name": "ROI24 Onboarding", + "steps": [ + {"id": "briefing", "label": "Брифинг клиента", "type": "process"}, + {"id": "audit", "label": "Аудит процессов", "type": "process"}, + {"id": "question", "label": "Процессы прозрачны?", "type": "decision"}, + {"id": "create", "label": "Создание схем", "type": "process"}, + {"id": "clarify", "label": "Уточняем процесс", "type": "process"}, + {"id": "approve", "label": "Согласование", "type": "process"}, + {"id": "end", "label": "Готово", "type": "end"}, + ], + "decisions": { + "question": [ + {"label": "Да", "target": "create"}, + {"label": "Нет", "target": "clarify"}, + ], + }, +} + +# Генерация D2 +def generate_d2(config): + lines = ["{"] + lines.append(' edgeStyle: round') + + for step in config["steps"]: + node_id = step["id"] + label = step["label"].replace('"', '\\"') + lines.append(f'{node_id}: "{label}"') + + # Связи + step_ids = [s["id"] for s in config["steps"]] + for i in range(len(step_ids) - 1): + src = step_ids[i] + tgt = step_ids[i + 1] + lines.append(f'{src} -> {tgt}') + + # Решения + for decision_id, branches in config["decisions"].items(): + for branch in branches: + lines.append(f'{decision_id} -> {branch["target"]}: {branch["label"]}') + + lines.append("}") + return "\n".join(lines) + +# Генерируем и рендерим +d2_content = generate_d2(process) +with open("output.d2", "w") as f: + f.write(d2_content) + +subprocess.run(["d2", "output.d2", "output.svg"]) +print("SVG generated: output.svg") +```