glam/frontend/public/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 - 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
• Dagre: dagrejs/dagre
• D3 Zoom: 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

Related Visualization Research

• Semantic Zoom for Ontologies: Fraunhofer 2024
• Multi-level Clustered Graphs: IEEE VIS 2020
• Minimap Navigation: AWS Diagram Maker Plugin

---

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!