glam/docs/UML_LAYOUT_OPTIONS.md

# UML Diagram Layout Options

**Live at**: https://bronhouder.nl/visualize  
**Last Updated**: December 2025

This document describes all available layout options for the Heritage Custodian Ontology UML visualization tool.

---

## Quick Selection Guide

| Your Goal | Recommended Layout | Why |
|-----------|-------------------|-----|
| Standard UML documentation | **Hierarchical (Top-Bottom)** | Classic, readable, professional |
| Exploring relationships | **Force Layout** | Organic clustering reveals patterns |
| Wide screen / horizontal flow | **Hierarchical (Left-Right)** | Utilizes horizontal space |
| Large diagram (50+ classes) | **Adaptive (Tight Tree)** | Compact, fits more on screen |
| Dependency analysis | **Adaptive (Longest Path)** | Emphasizes critical paths |
| Printing or export | **Adaptive (Tight Tree)** | Minimal whitespace |

---

## Available Layout Algorithms

### 1. Force Layout (Physics-Based)

**Algorithm**: D3.js force-directed simulation  
**Best For**: Exploratory analysis, discovering clusters  
**Animation**: Yes (~5 seconds to settle)

**Characteristics**:
- Nodes repel each other (collision avoidance)
- Edges act as springs (connected nodes pulled together)
- Organic, natural clustering
- Non-deterministic (layout changes on refresh)

**When to Use**:
- "Which classes are most connected?"
- "Are there natural groupings I haven't noticed?"
- Initial exploration of unfamiliar ontologies

**Limitations**:
- Slow for large diagrams (50+ nodes)
- No consistent positions (changes each time)
- Can be chaotic for highly connected graphs

---

### 2. Hierarchical (Top-Bottom)

**Algorithm**: Dagre with Sugiyama-style layered layout  
**Ranker**: Network Simplex (balanced ranking)  
**Best For**: Traditional UML class diagrams

**Characteristics**:
- Parent classes above children (inheritance flows downward)
- Even horizontal distribution
- Minimized edge crossings
- Deterministic (same input = same output)

**Technical Details**:
```
Direction: TB (Top to Bottom)
Ranker: network-simplex
Node separation: 80px horizontal
Rank separation: 120px vertical
```

**When to Use**:
- API documentation
- Architecture overviews
- Print-ready diagrams
- Tall monitors / portrait orientation

---

### 3. Hierarchical (Left-Right)

**Algorithm**: Dagre with horizontal flow  
**Ranker**: Network Simplex  
**Best For**: Process flows, wide screens

**Characteristics**:
- Parent classes left of children (flow left-to-right)
- Flowchart-style appearance
- Good for sequential processes

**Technical Details**:
```
Direction: LR (Left to Right)
Ranker: network-simplex
Node separation: 100px vertical
Rank separation: 150px horizontal
```

**When to Use**:
- State machine diagrams
- Ultrawide monitors
- Shallow but wide hierarchies
- Sequential transformations

---

### 4. Adaptive (Tight Tree)

**Algorithm**: Dagre with tight-tree ranker  
**Best For**: Large diagrams, compact presentations

**Characteristics**:
- Minimal whitespace
- Nodes packed closely
- Fast computation
- Greedy rank assignment

**Technical Details**:
```
Direction: TB (Top to Bottom)
Ranker: tight-tree
Complexity: O(N log N)
```

**When to Use**:
- 30+ class diagrams
- Printing (minimize pages)
- Small screens / mobile devices
- When space is at a premium

**Algorithm Details**:
The tight-tree ranker uses a greedy heuristic that prioritizes compactness over perfect symmetry. It builds a spanning tree and assigns ranks based on tree depth, resulting in layouts that use less vertical space than network-simplex.

---

### 5. Adaptive (Longest Path)

**Algorithm**: Dagre with longest-path ranker  
**Best For**: Dependency graphs, critical path analysis

**Characteristics**:
- Ranks nodes by longest path from source
- Emphasizes depth over width
- Highlights inheritance chains
- May create uneven horizontal distribution

**Technical Details**:
```
Direction: TB (Top to Bottom)
Ranker: longest-path
Complexity: O(N + E)
```

**When to Use**:
- "What's the deepest inheritance chain?"
- Dependency analysis
- Critical path visualization
- When hierarchy depth matters most

---

## Algorithm Comparison

### Speed Benchmarks

| Algorithm | 5 Nodes | 20 Nodes | 50+ Nodes |
|-----------|---------|----------|-----------|
| Force | ~2s | ~5s | ~10s+ |
| Network Simplex | <10ms | <50ms | <200ms |
| Tight Tree | <10ms | <30ms | <150ms |
| Longest Path | <10ms | <30ms | <100ms |

**Recommendation**: Use Dagre-based layouts (all except Force) for production diagrams.

### Quality Metrics

| Algorithm | Symmetry | Compactness | Consistency |
|-----------|----------|-------------|-------------|
| Force | High | Low | None (random) |
| Network Simplex | High | Medium | Yes |
| Tight Tree | Medium | High | Yes |
| Longest Path | Low | Low | Yes |

---

## Navigation Features

### Zoom Controls

- **Zoom In/Out**: Buttons or mouse wheel
- **Zoom Range**: 1% to 400%
- **Fit to Screen**: Auto-calculates optimal zoom to show entire diagram
- **Reset Zoom**: Returns to 100% centered

### Pan Navigation

- **Click + Drag**: Pan the canvas
- **Touch**: Two-finger drag on mobile

### Minimap (Planned)

Future enhancement: Small overview in corner showing current viewport position.

---

## Advanced Techniques for Large Diagrams

### Semantic Zoom

For very large ontologies (70+ classes), consider:

1. **Level-of-Detail (LOD)**: Hide properties at low zoom, show only class names
2. **Clustering**: Group related classes into collapsible modules
3. **Filtering**: Show only specific class hierarchies

### Recommended Workflow for Large Diagrams

1. Load diagram with **Tight Tree** layout (compact)
2. Use **Fit to Screen** to see everything
3. Zoom in to regions of interest
4. Switch to **Force Layout** to explore specific clusters

---

## Layout Algorithms Explained

### Sugiyama Framework (Dagre)

All hierarchical layouts use the Sugiyama framework:

1. **Cycle Removal**: Make graph acyclic
2. **Layer Assignment**: Assign nodes to vertical ranks
3. **Crossing Minimization**: Reduce edge crossings
4. **Coordinate Assignment**: Position nodes horizontally

The **ranker** parameter controls step 2 (Layer Assignment):

| Ranker | Strategy | Result |
|--------|----------|--------|
| network-simplex | Optimal LP solution | Balanced, professional |
| tight-tree | Greedy spanning tree | Compact, fast |
| longest-path | Topological order | Depth-focused |

### Force-Directed (D3)

Force simulation applies virtual physics:

- **Repulsion**: Nodes push each other away (Coulomb's law)
- **Attraction**: Edges pull connected nodes together (Hooke's law)
- **Center gravity**: Nodes pulled toward canvas center
- **Collision**: Nodes cannot overlap

The simulation runs ~300 ticks until energy dissipates.

---

## Future Layout Options

### Planned Enhancements

| Feature | Description | Status |
|---------|-------------|--------|
| **ELK Layout** | Eclipse Layout Kernel (advanced hierarchical) | Planned |
| **Cose-Bilkent** | Constraint-based force-directed | Planned |
| **Circular** | Nodes arranged in circle | Considered |
| **Radial** | Tree radiating from center | Considered |
| **Orthogonal** | Only horizontal/vertical edges | Research |

### ELK (Eclipse Layout Kernel)

ELK is a sophisticated layout engine used in professional UML tools. Key features:

- **Layered Layout**: Advanced Sugiyama with many optimizations
- **Stress Layout**: Force-directed with constraints
- **Orthogonal Edge Routing**: Clean 90-degree turns
- **Port Constraints**: Edges attach to specific node sides

### Orthogonal Edge Routing

Current implementation uses straight-line edges. Orthogonal routing would:

- Draw edges as sequences of horizontal/vertical segments
- Minimize edge crossings
- Follow "metro map" style
- Better for complex diagrams

Research: [HOLA Algorithm](https://marvl.infotech.monash.edu/~dwyer/papers/hola2015.pdf) - Human-like Orthogonal Layout

---

## Accessibility Considerations

### Keyboard Navigation (Planned)

Future shortcuts:
- `Ctrl+1` through `Ctrl+5`: Quick layout switch
- `+`/`-`: Zoom in/out
- `0`: Reset zoom
- `F`: Fit to screen
- Arrow keys: Pan canvas

### Screen Reader Support

Classes include ARIA labels with:
- Class name
- Number of properties
- Number of relationships
- Position in hierarchy

---

## Export Integration

Each layout can be exported to:

| Format | Preserves Layout | Editable |
|--------|------------------|----------|
| PNG | Yes | No |
| SVG | Yes | Yes (vector) |
| Mermaid | No (re-renders) | Yes |
| PlantUML | No (re-renders) | Yes |

**Tip**: For print-ready exports, use **Tight Tree** layout first, then export to SVG/PNG.

---

## Implementation References

### Libraries Used

- **D3.js Force**: [d3-force](https://github.com/d3/d3-force)
- **Dagre**: [dagrejs/dagre](https://github.com/dagrejs/dagre)
- **D3 Zoom**: [d3-zoom](https://github.com/d3/d3-zoom)

### Research Papers

1. **Sugiyama et al. (1981)**: "Methods for Visual Understanding of Hierarchical System Structures"
2. **Gansner et al. (1993)**: "A Technique for Drawing Directed Graphs" (Network Simplex)
3. **HOLA (2015)**: "Human-like Orthogonal Layout Algorithm"
4. **ELK Documentation**: [eclipse.org/elk](https://www.eclipse.org/elk/)

### Related Visualization Research

- **Semantic Zoom for Ontologies**: [Fraunhofer 2024](https://publica.fraunhofer.de/entities/publication/d99ba659-2a14-4c86-9228-f8d2c57e23e9)
- **Multi-level Clustered Graphs**: [IEEE VIS 2020](https://www.cg.tuwien.ac.at/research/publications/2020/wu-2020-tvcg/)
- **Minimap Navigation**: [AWS Diagram Maker Plugin](https://awslabs.github.io/diagram-maker-plugin-minimap/)

---

## Troubleshooting

### "Layout takes forever"

- Switch from **Force** to **Hierarchical** (10-100x faster)
- For 50+ nodes, use **Tight Tree**
- Check browser console for errors

### "Nodes overlap"

- Increase zoom level
- Try **Hierarchical TB** (better spacing)
- Use **Fit to Screen** first

### "Can't see entire diagram"

- Click **Fit to Screen** button
- Zoom out (now supports 1% minimum)
- Use **Tight Tree** for compact view

### "Layout looks wrong after switching diagrams"

- Click **Fit to Screen** to recenter
- Layout type persists in localStorage
- Try refreshing the page

---

## Version History

| Date | Change |
|------|--------|
| Dec 2025 | Extended zoom to 1%-400% range |
| Nov 2025 | Added 5 layout algorithms |
| Nov 2025 | Added Dagre grid layouts |
| Oct 2025 | Initial Force layout implementation |

---

**Live Demo**: https://bronhouder.nl/visualize

**Try It**: Load a UML diagram, click the "Layout" dropdown, and experiment with all 5 options!