summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/circular/doc.lua
blob: 0bd9090a1c106851f545c55f19c985313075c64c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
-- Copyright 2013 by Till Tantau
--
-- This file may be distributed an/or modified
--
-- 1. under the LaTeX Project Public License and/or
-- 2. under the GNU Public License
--
-- See the file doc/generic/pgf/licenses/LICENSE for more information

-- @release $Header$

local key           = require 'pgf.gd.doc'.key
local documentation = require 'pgf.gd.doc'.documentation
local summary       = require 'pgf.gd.doc'.summary
local example       = require 'pgf.gd.doc'.example


--------------------------------------------------------------------
key          "simple necklace layout"

summary
[[
This simple layout arranges the nodes in a circle, which is
especially useful for drawing, well, circles of nodes.
]]

documentation
[[
The name |simple necklace layout| is reminiscent of the more general
``necklace layout'', a term coined by Speckmann and Verbeek in
their paper
%
\begin{itemize}
  \item
    Bettina Speckmann and Kevin Verbeek,
    \newblock Necklace Maps,
    \newblock \emph{IEEE Transactions on Visualization and Computer
      Graphics,} 16(6):881--889, 2010.
\end{itemize}

For a |simple necklace layout|, the centers of the nodes
are placed on a counter-clockwise circle, starting with the first
node at the |grow| direction (for |grow'|, the circle is
clockwise). The order of the nodes is the order in which they appear
in the graph, the edges are not taken into consideration, unless the
|componentwise| option is given.
%
\begin{codeexample}[]
\tikz[>=spaced stealth']
  \graph [simple necklace layout, grow'=down, node sep=1em,
          nodes={draw,circle}, math nodes]
  {
    x_1 -> x_2 -> x_3 -> x_4 ->
    x_5 -> "\dots"[draw=none] -> "x_{n-1}" -> x_n -> x_1
  };
\end{codeexample}

When you give the |componentwise| option, the graph will be
decomposed into connected components, which are then laid out
individually and packed using the usual component packing
mechanisms:
%
\begin{codeexample}[]
\tikz \graph [simple necklace layout] {
  a -- b -- c -- d -- a,
  1 -- 2 -- 3 -- 1
};
\end{codeexample}
%
\begin{codeexample}[]
\tikz \graph [simple necklace layout, componentwise] {
  a -- b -- c -- d -- a,
  1 -- 2 -- 3 -- 1
};
\end{codeexample}

The nodes are placed in such a way that
%
\begin{enumerate}
  \item The (angular) distance between the centers of consecutive
    nodes is at least  |node distance|,
  \item the distance between the borders of consecutive nodes is at
    least |node sep|, and
  \item the radius is at least |radius|.
\end{enumerate}
%
The radius of the circle is chosen near-minimal such that the above
properties are satisfied. To be more precise, if all nodes are
circles, the radius is chosen optimally while for, say, rectangular
nodes there may be too much space between the nodes in order to
satisfy the second condition.
]]

example
[[
\tikz \graph [simple necklace layout,
              node sep=0pt, node distance=0pt,
              nodes={draw,circle}]
{ 1 -- 2 [minimum size=30pt] -- 3 --
  4 [minimum size=50pt] -- 5 [minimum size=40pt] -- 6 -- 7 };
]]

example
[[
\begin{tikzpicture}[radius=1.25cm]
  \graph [simple necklace layout,
          node sep=0pt, node distance=0pt,
          nodes={draw,circle}]
  { 1 -- 2 [minimum size=30pt] -- 3 --
    4 [minimum size=50pt] -- 5 [minimum size=40pt] -- 6 -- 7 };

  \draw [red] (0,-1.25) circle [];
\end{tikzpicture}
]]

example
[[
\tikz \graph [simple necklace layout,
              node sep=0pt, node distance=1cm,
              nodes={draw,circle}]
{ 1 -- 2 [minimum size=30pt] -- 3 --
  4 [minimum size=50pt] -- 5 [minimum size=40pt] -- 6 -- 7 };
]]

example
[[
\tikz \graph [simple necklace layout,
              node sep=2pt, node distance=0pt,
              nodes={draw,circle}]
{ 1 -- 2 [minimum size=30pt] -- 3 --
  4 [minimum size=50pt] -- 5 [minimum size=40pt] -- 6 -- 7 };
]]

example
[[
\tikz \graph [simple necklace layout,
              node sep=0pt, node distance=0pt,
              nodes={rectangle,draw}]
{ 1 -- 2 [minimum size=30pt] -- 3 --
  4 [minimum size=50pt] -- 5 [minimum size=40pt] -- 6 -- 7 };
]]
--------------------------------------------------------------------