Graph::Easy - Manual - Hinting aka generating specific layouts

# Graph::Easy - Manual

## Hinting - or how to create specific graph layouts

If you haven't done so, please read the Overview first, followed by the chapter about the Layouter details.

This chapter gives an overview over all the different hints you can give the layouter on how to layout the graph. For specific, visual examples, please see the tutorial chapters.

### Introduction

Graph::Easy's layouter is responsible for converting a (internal) graph representation into a specific layout. Here are two example layouts, automatically produced from the same input graph:

    +---+     +---+     +---+
    | A | --> | C | --> | D |
    +---+     +---+     +---+
                |
                |
                v
              +---+
              | E |
              +---+

### Influencing the Layout

Although the placement of nodes, edges and labels is completely automated, you can influence the created layout by giving the layouter hints like the following:

- adjusting the flow direction
- setting node sizes
- grouping nodes together
- Creating rows/columns of nodes
- Placing nodes relativ to each other
- Enforcing edge lengths and minimum distances
- placing nodes relativ to each other
- specify edge starting/ending ports

Some of the hints will be used only as hints by the layouter, e.g. it might ignore them to produce a complete layout. Other hints like relative node placements are taken as strict "must do", and these might create dilemmas for the layouter. So use them only when absolutely neccessary.

### Flow Control

You can use the attribute flow to let the graph flow in another general direction:

#### Flow-dependend and Flow-independend Directions

Flow can be specified either absolut (giving absolut directions like `south` or `west`), or relative (directions `left`, `front` etc that are relative to the local flow at that node).

#### Controlling the Overall Graph Flow

    graph { flow: south; }

    [ Hamm ] -> [ Essen ] -> [ Olpe ]

    +-------+
    | Hamm  |
    +-------+
      |
      |
      v
    +-------+
    | Essen |
    +-------+
      |
      |
      v
    +-------+
    | Olpe  |
    +-------+

    graph { flow: west; }

    [ Hamm ] -> [ Essen ] -> [ Olpe ]

    +------+     +-------+     +------+
    | Olpe | <-- | Essen | <-- | Hamm |
    +------+     +-------+     +------+

All four flow directions (north, south, west, east) are supported, even when generating `graphviz` code (dot does not easily support upwards and leftwards flow directions without some trickery).

#### Controlling the Flow per Node

You can also change the flow on a per-node basis.
In the next example the node Siegen has a flow towards `west` (because this is the general flow of the graph). The default flow for all its outgoing edges is then modified to be `left`, which amounts to `south`, since looking westwards and turning left 90 degress will make you looking southwards:

    graph { flow: west; }

    [ Duisburg ] -> [ Siegen ] { flow: south; }
     -> [ Adenau ]

    +--------+     +----------+
    | Siegen | <-- | Duisburg |
    +--------+     +----------+
      |
      |
      v
    +--------+
    | Adenau |
    +--------+

#### Controlling the Flow per Edge

You can also set the flow direction for each edge on its own. We modify the example above by adding another node. Instead of relying on the out-going flow from Siegen, we give this edge its own flow, namely `up`. (`right` would have worked, too. In fact, relative flow is always better, we will see below why.)

    graph { flow: west; }

    [ Duisburg ] -> [ Siegen ] { flow: left; }
     -> [ Adenau ]
    [ Siegen ] -> { flow: up; } [ Monschau ]

    +----------+
    | Monschau |
    +----------+
      ^
      |
      |
    +----------+     +----------+
    |  Siegen  | <-- | Duisburg |
    +----------+     +----------+
      |
      |
      v
    +----------+
    |  Adenau  |
    +----------+

### Edge start/end ports

Before we continue with the differences between relative and absolute flow, let's just have a look at `port numbers` and `sides`:

    ..................................................
    :      :       :       :       :     :     :     :
    : 0,0  :north,0:north,1: 3,0   : 4,0 : 5,0 : 6,0 :
    :      :left,0 :left,1 :       :     :     :     :
    :      :       :       :       :     :     :     :
    ..................................................
    :      :+-------------+:       :     :     :     :
    :west,0:|             |:east,0 : 4,1 : 5,1 : 6,1 :
    :back,1:|             |:front,0:     :     :     :
    :      :|             |:       :     :     :     :
    ........|    Node     |...........................
    :      :|             |:       :     :     :     :
    :west,1:|             |:east,1 : 4,2 : 5,2 : 6,2 :
    :back,1:|             |:front,1:     :     :     :
    :      :+-------------+:       :     :     :     :
    .................................................
    :      :       :       :       :     :     :     :
    : 0,3  :south,0:south,1: 3,3   : 4,3 : 5,3 : 6,3 :
    :      :right,0:right,1:       :     :     :     :
    :      :       :       :       :     :     :     :
    .................................................

Each side of a node can be named. The reason that there are two names (`north` and `left`) has to do with graph/node flow. The south side of the node is always the same side, no matter what the flow at the node is. The `right` side is always perpendicular to the `front` side - and the front side always points in the direction of the flow. Here is an example that should make this clear:

    [ C ] -> { start: south; } [ S ] { origin: C; offset: 0,2; }
    [ C ] -> { start: north; } [ N ] { origin: C; offset: 0,-2; }
    [ C ] -> { start: east; }  [ E ] { origin: C; offset: 2,0; }
    [ C ] -> { start: west; }  [ W ] { origin: C; offset: -2,0; }

              +---+
              | N |
              +---+
                ^
                |
                |
    +---+     +---+     +---+
    | W | <-- | C | --> | E |
    +---+     +---+     +---+
                |
                |
                v
              +---+
              | S |
              +---+

    [ C ] -> { start: right; } [ R ] { origin: C; offset: 0,2; }
    [ C ] -> { start: left; }  [ L ] { origin: C; offset: 0,-2; }
    [ C ] -> { start: front; } [ F ] { origin: C; offset: 2,0; }
    [ C ] -> { start: back; }  [ B ] { origin: C; offset: -2,0; }

              +---+
              | L |
              +---+
                ^
                |
                |
    +---+     +---+     +---+
    | B | <-- | C | --> | F |
    +---+     +---+     +---+
                |
                |
                v
              +---+
              | R |
              +---+

Both graphs look the same, so there does not seem much point in using `right` or `south`. However changing the flow of the graph will show a difference:

    graph { flow: down; }

    [ C ] -> { start: south; } [ S ] { origin: C; offset: 0,2; }
    [ C ] -> { start: north; } [ N ] { origin: C; offset: 0,-2; }
    [ C ] -> { start: east; }  [ E ] { origin: C; offset: 2,0; }
    [ C ] -> { start: west; }  [ W ] { origin: C; offset: -2,0; }

              +---+
              | N |
              +---+
                ^
                |
                |
    +---+     +---+     +---+
    | W | <-- | C | --> | E |
    +---+     +---+     +---+
                |
                |
                v
              +---+
              | S |
              +---+

    graph { flow: down; }

    [ C ] -> { start: right; } [ R ] { origin: C; offset: 0,2; }
    [ C ] -> { start: left; }  [ L ] { origin: C; offset: 0,-2; }
    [ C ] -> { start: front; } [ F ] { origin: C; offset: 2,0; }
    [ C ] -> { start: back; }  [ B ] { origin: C; offset: -2,0; }

              +---+
              | L | <+
              +---+  |
                     |
      +---------+    |
      v         |    |
    +---+     +---+  |  +---+
    | B |  +- | C | -+  | F |
    +---+  |  +---+     +---+
           |    |         ^
           |    +---------+
           |
           |  +---+
           +> | R |
              +---+

You can see that the first graph did not change at all.
The second one looks different, though. Since the node offsets are fixed (they do not change with the flow, as this is not possible yet), all the nodes are still placed at the same position. But the starting ports moved (rotated) with the flow direction!

Summary: To make graphs flow-invariant, use south etc, to make it possible to rotate graphs, use `left`, `right`, `front` or `back`.

Here is one more example:

    graph { flow: east; }

    [1 - turn back]
     --> {flow: back } [2 - turn left]
     --> {flow: left } [3 - turn left]
     --> {flow: left } [4 - turn right]
     --> {flow: right } [5 - turn right]
     --> {flow: right } [6 - finished]

    +---------------+     +----------------+
    | 2 - turn left | <-- | 1 - turn back  |
    +---------------+     +----------------+
      |
      |
      v
    +---------------+     +----------------+
    | 3 - turn left | --> | 4 - turn right |
    +---------------+     +----------------+
                            |
                            |
                            v
    +---------------+     +----------------+
    | 6 - finished  | <-- | 5 - turn right |
    +---------------+     +----------------+

#### Port numbers

By setting the start/end port to one side, you instruct the layouter to place the edge on one arbitrary port on that side:

    [ Left ] -> { start: left; end: left; } [ Right ]

      +------------+
      |            v
    +------+     +-------+
    | Left |     | Right |
    +------+     +-------+

### Joins (Edge Splicing and Splitting

Whenever two (or more) edges share one common start port (not just one side, like `south`), they will split up somewhere along their path.
Likewise, when two or more edges share one common end port, the edges will joint up somewhere on their way to the target node:

     [ Potsdam ], [ Mannheim ]
       --> { end: back,0; }
     [ Weimar ]
       --> { start: front,0; } [ Finsterwalde ], [ Aachen ]

    +----------+           +--------+          +--------------+
    | Mannheim | ------+-> | Weimar | -+-----> | Finsterwalde |
    +----------+       |   +--------+  |       +--------------+
                       |               |
                       |               |
                       |               |
    +----------+       |               |       +--------------+
    | Potsdam  | ------+               +-----> |    Aachen    |
    +----------+                               +--------------+

This works even in combination with edge labels:

    [ Jena ]
     -- train --> { start: front, 0; }
      [ Augsburg ], [ Ulm ]
    [ Jena ] -- car --> { start: front, 0; } [ Plauen ]

    +------+           train    +----------+
    | Jena | ------+----------> |   Ulm    |
    +------+       |            +----------+
                   |   train    +----------+
                   +----------> | Augsburg |
                   |            +----------+
                   |    car     +----------+
                   +----------> |  Plauen  |
                                +----------+

### Node sizes (multi-celled nodes)

You can specify the size of a node in rows and columns by using either the `rows`, `columns` or `size` attribute:

    [ A ] { size: 2,2; }
    -> [ B ] { rows: 2; }
    -> [ C ] { columns: 3; }

Here is an example that demonstrates this:

    [ A ] { size: 2,2; }
    -> [ B ] { rows: 2; }
    -> [ C ] { columns: 3; }

    [ A ] -> [ B ]
     -> [ C ]
     -> [ D ]

    [ D ] -> [ C ]
    [ B ] -> [ C ]

    [ A ] -> [ F ]
    [ A ] -> [ G ]

                          +---------+    +---------+
                          |         v    v         |
    +---+     +---+     +---+     +--------+     +---+
    | G | <-- |   | --> |   | --> |   C    | --> | D |
    +---+     | A |     | B |     +--------+     +---+
              |   |     |   |       ^
              |   | --> |   | ------+
              +---+     +---+
                |
                |
                v
              +---+
              | F |
              +---+

Even when you do not specify a size, the layouter will grow nodes automatically to satisfy the constraints of the layout, for instance when more than four edges start/end at a particular node. Likewise, when specifying edge ports (see above), these constraints will grow the node if necessary.
As an example, if you specifiy that there are 5 edges starting/ending at the south side of the node, than the node will be made at least 5 cells wide.

### Groups

Nodes can be grouped together by using braces, thus creating a subgraph (or cluster). A group gives the layouter the hint that these nodes are related and should be laid out closely together:

    ( German Cities
      [ Berlin ] -> [ Potsdam ]
    ) {
      border-style: dashed;
      }

    ...................................
    : German Cities:                  :
    :                                 :
    : +-------------+     +---------+ :
    : |   Berlin    | --> | Potsdam | :
    : +-------------+     +---------+ :
    :                                 :
    :.................................:

Note: Groups can not yet be nested.

The grouping feature is especially powerfull in combination with the `nodeclass` attribute:

    node.cities { color: blue; }

    ( German Cities
      [ Berlin ] -> [ Potsdam ]
    ) {
      border-style: dashed;
      nodeclass: cities;
      }

In this example, all nodes in the group will automatically be put into the class `node.cities`.

You can also defined edges that run from one group to another, or from a node to a group, or from a group to a node:

    [ From Node to Group ] -->

    ( German cities:
      [ Berlin ] -> [ Potsdam ]
    )

      -- group to group -->

    ( German rivers:
      [ Rhein ] -> [ Elbe ]
    )

    --> [ From Group to Node ]

### Relative placement (via minlen)

Sometimes you want to enforce a minimum distance between different nodes. To achive this, you can set the minlen attribute on an edge. If necessary, you can also set the edge to `invisible` to hide it from view:

    [ Aachen ] --> [ Bonn ] --> [ Coburg ]
    [ Aue ] --> { minlen: 3; } [ Cuxhaven ]

    +--------+     +------+     +----------+
    | Aachen | --> | Bonn | --> |  Coburg  |
    +--------+     +------+     +----------+
    +--------+                  +----------+
    |  Aue   | ---------------> | Cuxhaven |
    +--------+                  +----------+

The advantage of setting a minlen on an edge is that the distance is enforced in the direction of the flow, e.g. with an relative flow the distance becomes rotation-invariant. If one would use a relative placement via `offset`, the two nodes would be always placed with the same offset from each other, no matter what the flow of the graph is.

### Relative placement (via auto-split)

You can cluster nodes together by placing them relatively to each other.
Perhaps the easiest way to achive the placement is to use the auto-split feature:

- a `|` (vertical bar) in the node name will split the node into two parts, and place them next to each other, horizontally
- likewise, `||` (two vertical bars) in the node name will split the node into two parts, but place the second part at the start of a new row
- If a part between two `|` consists of exactly one space, an invisible cell will be generated, e.g. one without borders and background
- If a part between two `|` consists of more than one space, an empty cell (e.g. with borders and background) will be generated
- Trailing empty parts will be treated just like when they apeared in the middle, e.g. both `[ |...` and `[|..-` create an invisible leading part, while `[ |...` (two spaces) creates an empty, but visible leading part. Likewise for trailing parts.

Here is a few examples to make this clear:

    [ A | B | C ]

    +---+---+---+
    | A | B | C |
    +---+---+---+

    [ A | B || C ]

    +---+---+
    | A | B |
    +---+---+
    | C |
    +---+

    [ A | B ||
      C | D | E ||
      F ]

    +---+---+
    | A | B |
    +---+---+---+
    | C | D | E |
    +---+---+---+
    | F |
    +---+

And now an example showing empty trailing and leading parts:

    [  | C |  ]
    [ | D |  ]
    [  | E | ]
    [ | F | ]
    [|G|]
    [  |H| |]

    [ C.2 ] -> [ A1 ]
    [ D.2 ] -> [ A2 ]
    [ E.2 ] -> [ A3 ]
    [ F.2 ] -> [ A4 ]
    [ G.2 ] -> [ A5 ]
    [ H.3 ] -> [ A6 ]

        +--+---+--+     +----+
        |  | C |  | --> | A1 |
        +--+---+--+     +----+
           |---+--+     +----+
           | D |  | --> | A2 |
            ---+--+     +----+
        +--+---+        +----+
        |  | E |    --> | A3 |
        +--+---+        +----+
           |---+        +----+
           | F |    --> | A4 |
            ---+        +----+
           |---+        +----+
           | G |    --> | A5 |
            ---+        +----+
    +--+---+            +----+
    |  | H |        --> | A6 |
    +--+---+            +----+

Please see the section about attributes on how to put individual attributes on each autosplit node.

To reference an autosplit node, you need to know its basename and the number of the part that was split up. The basename can be set via an attribute. If not specified, it will be automatically created by concatenating all the parts together, without spaces or linebreaks. If the basename already exists, an incrementing number is appended (including a leading "-"), starting with "1":

    [ A | B | C ]		# basename is: ABC
    [ A | B | C ]		# basename is: ABC-1

In this example, the basename for the first autosplit node is "ABC", the second one get's as basename "ABC-1".

    [ A | B | C ]		# basename: ABC
    [ A | B | C ]		# basename: ABC-1
    [ C | D | E ]		# basename: CDE
    [ C | D | E ]		# basename: CDE-2

Note that the number is unique and increasing for the entire graph, thus creating "CDE" and "CDE-2", and not "CDE-1" in the second example.

The parts are referenced by their number, with a leading ".". Here is an example referencing the second part of the autosplit node:

    [ A | B | C ]
    [ 1 ] -> [ ABC.2 ]

             +---+
             | 1 |
             +---+
               |
               |
               v
    +---+---+----+
    | A | B |  C |
    +---+---+----+

Here is a more complex example, using the basename attribute:

    [ A|B|C ] { basename: A } [ 1 ] -> [ A.2 ]
    [ A|B|C ] [ 2 ] -> [ ABC-1.2 ]

This will be rendered like so:

             +---+
             | 2 |
             +---+
               |
               |
               v
    +---+---+----+
    | A | B |  C |
    +---+---+----+
             +---+
             | 1 |
             +---+
               |
               |
               v
    +---+---+----+
    | A | B |  C |
    +---+---+----+

### Relative Node Placement (with offsets)

Another way is to specify an `origin` and `offset` for a node, placing it relatively to another node:

    [ Left ] -> [ Right ] { origin: Left; offset: 2,1; }

    +------+
    | Left |
    +------+
      |
      |              +-------+
      +------------> | Right |
                     +-------+

The offset should not be `0,0`. Also, be carefull to node place nodes inside each other, especially when using multicelled nodes as explained above.

The offset is calculated from the left/right or top/bottom side of the node, so for a multicelled node that is 3 cells wide, an offset of 2 would still place the next node two cells from the right side (instead inside the first node):

    [ A ] { size: 3,2; }

    [ A ] -> [ B ] { origin: A; offset: 2,0; }
    [ A ] -> [ C ] { origin: A; offset: 1,1; }

    +---+     +---+
    |   | --> | B |
    | A |     +---+
    |   |
    |   |--+
    +---+  v
         +---+
         | C |
         +---+

You can set an `origin` for each node, even if this node has an origin itself. The only exception is that you may not create loops like in the following:

    [ A ] { origin: B; offset: 1,1; }
    [ B ] { origin: A; offset: 1,1; }       # invalid!

    [ C ] { origin: E; offset: 1,1; }
    [ D ] { origin: C; offset: 1,1; }
    [ E ] { origin: C; offset: 1,1; }       # invalid!

And here is an example, using a chain of origins:

    [ A ] { origin: B; offset: 2,1; }

    -> [ B ] { origin: C; offset: 1,1; }
    -> [ C ] { origin: D; offset: 1,1; }
    -> [ D ]
    -> [ E ]

    +---+     +---+
    | D | --> | E |
    +---+     +---+
      ^  +---+
      +--| C |
         +---+
           ^  +---+
           +--| B |
              +---+
                ^       +---+
                +------ | A |
                        +---+

Please continue with the chapter about the A* algorithm for details on pathfinding.