summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/circular/doc.lua
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/circular/doc.lua')
-rw-r--r--graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/circular/doc.lua145
1 files changed, 145 insertions, 0 deletions
diff --git a/graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/circular/doc.lua b/graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/circular/doc.lua
new file mode 100644
index 0000000000..9198885965
--- /dev/null
+++ b/graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/circular/doc.lua
@@ -0,0 +1,145 @@
+-- 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}[
+ preamble={\usetikzlibrary{arrows.meta,graphs,graphdrawing}
+ \usegdlibrary{circular}}]
+\tikz[>={Stealth[round,sep]}]
+ \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}[preamble={\usetikzlibrary{graphs,graphdrawing}
+ \usegdlibrary{circular}}]
+\tikz \graph [simple necklace layout] {
+ a -- b -- c -- d -- a,
+ 1 -- 2 -- 3 -- 1
+};
+\end{codeexample}
+%
+\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
+ \usegdlibrary{circular}}]
+\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 };
+]]
+--------------------------------------------------------------------