mirror of
https://github.com/mermaid-js/mermaid.git
synced 2025-09-13 20:39:38 +02:00
139 lines
5.9 KiB
Markdown
139 lines
5.9 KiB
Markdown
> **Warning**
|
|
>
|
|
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
|
>
|
|
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/layouts/introduction.md](../../packages/mermaid/src/docs/layouts/introduction.md).
|
|
|
|
# 📊 Layout Algorithms in Mermaid
|
|
|
|
Mermaid is a popular JavaScript-based diagramming tool that supports auto-layout for graphs using pluggable layout engines. Layout algorithms play a critical role in rendering nodes and edges in a clean, readable, and meaningful way. Mermaid currently uses engines like **Dagre** and **ELK**, and will soon introduce a powerful new layout engine: **IPSep-CoLa**.
|
|
|
|
---
|
|
|
|
## 🔹 Dagre Layout
|
|
|
|
**Dagre** is a layout engine inspired by the **Sugiyama algorithm**, optimized for directed acyclic graphs (DAGs). It arranges nodes in layers and computes edge routing to minimize crossings and improve readability.
|
|
|
|
### Key Features:
|
|
|
|
- **Layered (Sugiyama-style) layout**: Ideal for top-down or left-to-right flow.
|
|
- **Edge routing**: Attempts to reduce edge crossings and bends.
|
|
- **Ranking**: Vertices are assigned ranks to group related elements into the same level.
|
|
- **Lightweight and fast**: Suitable for small to medium-sized graphs.
|
|
|
|
### Technical Overview:
|
|
|
|
- Works in four stages:
|
|
1. **Cycle Removal**
|
|
2. **Layer Assignment**
|
|
3. **Node Ordering**
|
|
4. **Coordinate Assignment**
|
|
- Outputs crisp layouts where edge direction is clear and logical.
|
|
|
|
### Limitations:
|
|
|
|
- No native support for **grouped or nested structures**.
|
|
- Not ideal for graphs with **non-hierarchical** or **dense cyclic connections**.
|
|
- Limited edge label placement capabilities.
|
|
|
|
---
|
|
|
|
## 🔸 ELK (Eclipse Layout Kernel)
|
|
|
|
**ELK** is a modular, extensible layout framework developed as part of the Eclipse ecosystem. It supports a wide variety of graph types and layout strategies.
|
|
|
|
### Key Features:
|
|
|
|
- **Multiple layout styles**: Hierarchical, force-based, layered, orthogonal, etc.
|
|
- **Support for ports**: Allows fine-grained edge anchoring on specific sides of nodes.
|
|
- **Group and hierarchy awareness**: Ideal for nested and compartmentalized diagrams.
|
|
- **Rich configuration**: Offers control over spacing, edge routing, direction, padding, and more.
|
|
|
|
### Technical Overview:
|
|
|
|
- Uses a **model-driven approach** with a well-defined intermediate representation (ELK Graph Model).
|
|
- Different engines are plugged in depending on the chosen layout strategy.
|
|
- Works well with large, complex, and deeply nested graphs.
|
|
|
|
### Limitations:
|
|
|
|
- Requires verbose configuration for best results.
|
|
- Can be slower than Dagre for small or simple diagrams.
|
|
- More complex to integrate and control dynamically.
|
|
|
|
---
|
|
|
|
## 🆕 IPSep-CoLa
|
|
|
|
### 🌐 Introduction
|
|
|
|
**IPSep-CoLa** stands for **Incremental Procedure for Separation Constraint Layout**, a next-generation layout algorithm tailored for **grouped, nested, and labeled graphs**. It is an enhancement over standard force-directed layouts, offering constraint enforcement and iterative refinement.
|
|
|
|
It is particularly useful for diagrams where:
|
|
|
|
- **Group integrity** is important (e.g., modules, clusters).
|
|
- **Edge labels** need smart placement.
|
|
- **Overlaps** must be prevented even under tight space constraints.
|
|
|
|
---
|
|
|
|
### ⚙️ How IPSep-CoLa Works
|
|
|
|
#### 1. **Constraint-Based Force Simulation**:
|
|
|
|
It builds on top of standard force-directed approaches (like CoLa), but adds **constraints** to influence the final positions of nodes:
|
|
|
|
- **Separation constraints**: Minimum distances between nodes, edge labels, and groups.
|
|
- **Containment constraints**: Child nodes must stay within the bounds of parent groups.
|
|
- **Alignment constraints**: Nodes can be aligned in rows or columns if desired.
|
|
|
|
#### 2. **Incremental Refinement**:
|
|
|
|
Unlike one-pass algorithms, IPSep-CoLa works in **phases**:
|
|
|
|
- Initial layout is produced using a base force simulation.
|
|
- The layout is iteratively adjusted using **constraint solvers**.
|
|
- Additional forces (spring, collision avoidance, containment) are incrementally added.
|
|
|
|
#### 3. **Edge Label Handling**:
|
|
|
|
One of the distinguishing features of IPSep-CoLa is its support for **multi-segment edge routing with mid-edge label positioning**, ensuring labels do not clutter or overlap.
|
|
|
|
---
|
|
|
|
### 📌 Use Cases
|
|
|
|
IPSep-CoLa is ideal for:
|
|
|
|
- **Hierarchical graphs** with complex nesting (e.g., software architecture, UML diagrams).
|
|
- **Clustered views** (e.g., social network groupings).
|
|
- **Diagrams with heavy labeling** where label placement affects readability.
|
|
- **Diagrams with strict visual structure** needs — maintaining boundaries, margins, or padding.
|
|
|
|
---
|
|
|
|
## 🔍 Comparison Table
|
|
|
|
| Feature | Dagre | ELK | IPSep-CoLa |
|
|
| ------------------------- | ----------- | ------------------- | ------------------------------ |
|
|
| Layout Type | Layered DAG | Modular (varied) | Constraint-driven force layout |
|
|
| Edge Labeling | ⚠️ Basic | ✅ Yes | ✅ Smart Placement |
|
|
| Overlap Avoidance | ⚠️ Partial | ✅ Configurable | ✅ Automatic |
|
|
| Layout Performance | ✅ Fast | ⚠️ Medium | ⚠️ Medium |
|
|
| Customization Flexibility | ⚠️ Limited | ✅ Extensive | ✅ Moderate to High |
|
|
| Best For | Simple DAGs | Complex hierarchies | Grouped and labeled graphs |
|
|
|
|
---
|
|
|
|
## 🧾 Summary
|
|
|
|
Each layout engine in Mermaid serves a different purpose:
|
|
|
|
- **Dagre** is best for fast, simple, and readable DAGs.
|
|
- **ELK** is powerful for modular, layered, or port-based diagrams with a need for rich customization.
|
|
- **IPSep-CoLa** will soon offer a flexible, constraint-respecting layout engine that excels at **visual clarity in grouped and complex diagrams**.
|
|
|
|
The addition of IPSep-CoLa to Mermaid's layout stack represents a significant leap forward in layout control and quality — making it easier than ever to visualize rich, structured, and annotated graphs.
|
|
|
|
---
|