Eclipse Layout Kernel (ELK) Documentation

The Eclipse Layout Kernel (ELK) provides an infrastructure designed to bridge diagram editors or viewers with automatic layout algorithms. It serves two primary purposes:

1. Providing a standard interface for tools to request layouts.
2. Supplying built-in layout algorithms that can be used immediately without custom implementation.

Developers typically interact with ELK as either tool developers (integrating layout into an editor) or algorithm developers (implementing new layout logic using ELK's graph data structures).

The ELK reference documentation is organized into three primary areas to help you configure layouts:

1. Layout algorithms: A list of available algorithms. To use an algorithm, you must provide its unique identifier. This section also details the specific layout options supported by each algorithm.
2. Layout options: A comprehensive list of all available configuration parameters used to tune layout algorithms. It is recommended to first identify your desired algorithm and then consult this section to see which options it supports.
3. Layout option groups: A categorization of layout options into logical groups, useful for understanding the relationship between different configuration parameters.

When designing a layout algorithm, you must decide whether a component should be implemented as a Phase or an Intermediate Processor. Use these guidelines:

• Use a Phase if the component is an essential, fundamental part of the algorithm that is always present, or if you want to allow different implementations of that specific stage (e.g., different ways to handle a 'sizing' stage).
• Use an Intermediate Processor for logic that is more granular or optional within a specific processing slot.

ELK supports two types of edges. While primitive edges are used for legacy support, extended edges are the standard for exported graphs.

Primitive Edges

Used for legacy models. They connect a single source node to a single target node.

{
  "source*": "node-id",
  "sourcePort": "port-id",
  "target*": "node-id",
  "targetPort": "port-id",
  "sourcePoint": { "x": 0, "y": 0 },
  "targetPoint": { "x": 0, "y": 0 },
  "bendPoints": [ { "x": 5, "y": 5 } ],
  "labels": [ { "text": "label text" } ]
}

Extended Edges

Supports hyperedges (connecting multiple sources to multiple targets). They use arrays of identifiers for sources and targets.

{
  "sources*": [ "node-id-1", "port-id-1" ],
  "targets*": [ "node-id-2", "port-id-2" ],
  "sections": [ { "startPoint": { "x": 0, "y": 0 } } ],
  "labels": [ { "text": "label text" } ]
}

To help the layout engine determine node sizes before the actual layout computation, you can assign a TopdownSizeApproximator to HIERARCHICAL_NODEs.

One available implementation is COUNT_CHILDREN, which calculates the proportional factor for node sizes using sqrt(number_of_children). You can also implement custom, arbitrarily complex size approximators.

If UI components are installed, ELK provides a Layout View within the workbench. This view acts as a specialized properties view designed specifically for configuring layout properties.

Key Behaviors:

• Selection Awareness: It listens to selection changes in the workbench.
• Automatic Activation: If the selected item is recognized as an element of a graph that ELK can layout, the view allows users to customize the specific layout options for that element.

Usage Note: Because the available layout options are numerous and highly technical (requiring knowledge of layout algorithms), the Layout View is primarily intended for tool developers and power users rather than general end-users.

In ELK, spacing can be applied to several core graph elements. These elements are treated differently depending on their geometry:

• Nodes, Ports, and Labels: These are treated as 'boxes' with space to be left around them.
• Edges: These are not treated as boxes.
• Connected Components: These may have more complex geometries than simple boxes.

Additionally, the ELK Layered algorithm introduces the concept of layers, which provides specific spacing options for controlling distances between layers.

The ShrinkTree approach is a method for node overlap removal based on a modified algorithm by Nachmanson et al. It follows these steps:

1. Triangulation: A Delaunay triangulation is performed on the set of vertices representing the nodes' centers.
2. Tree Construction: A spanning tree is constructed using the edges from the Delaunay triangulation.
3. Shrinking: The spanning tree is 'shrunk,' which pulls the nodes closer together to compact the layout.