summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/Distances.lua
blob: 6dc5a13018d4a3444fe05f53bbecde6b1383a4df (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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
-- Copyright 2012 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 declare       = require "pgf.gd.interface.InterfaceToAlgorithms".declare
local lib           = require "pgf.gd.lib"

---
-- @section subsection {Padding and Node Distances}
--
-- \label{subsection-gd-dist-pad}
--
-- In many drawings, you may wish to specify how ``near'' two nodes should
-- be placed by a graph drawing algorithm. Naturally, this depends
-- strongly on the specifics of the algorithm, but there are a number of
-- general keys that will be used by many algorithms.
--
-- There are different kinds of objects for which you can specify
-- distances and paddings:
-- %
-- \begin{itemize}
--   \item You specify the ``natural'' distance between nodes
--     connected by an edge using |node distance|, which is also available in
--     normal \tikzname\ albeit for a slightly different purpose. However,
--     not every algorithm will (or can) honor the key; see the description
--     of each algorithm what it will ``make of this option''.
--   \item A number of graph drawing algorithms arrange nodes in layers
--     (or levels); we refer
--     to the nodes on the same layer as siblings (although, in a tree,
--     siblings are only nodes with the same parent; nevertheless we use
--     ``sibling'' loosely also for nodes that are more like ``cousins'').
--   \item When a graph consists of several connected component, many graph
--     drawing algorithms will layout these components individually. The
--     different components will then be arranged next to each other, see
--     Section~\ref{section-gd-packing} for the details, such that between
--     the nodes of any two components a padding is available.
-- \end{itemize}
--
-- @end




---

declare {
  key = "node distance",
  type = "length",
  initial = "1cm",

  summary = [["
    This is minimum distance that the centers of nodes connected by an
    edge should have. It will not always be possible to satisfy this
    desired distance, for instance in case the nodes are too big. In
    this case, the \meta{length} is just considered as a lower bound.
  "]],
  examples = [["
    \begin{tikzpicture}
      \graph [simple necklace layout,  node distance=1cm, node sep=0pt,
              nodes={draw,circle,as=.}]
      {
        1 -- 2 [minimum size=2cm] -- 3 --
        4 -- 5 -- 6 -- 7 --[orient=up] 8
      };
      \draw [red,|-|] (1.center) -- ++(0:1cm);
      \draw [red,|-|] (5.center) -- ++(180:1cm);
    \end{tikzpicture}
  "]]
}


---

declare {
  key = "node pre sep",
  type = "length",
  initial = ".333em",

  summary = [["
    This is a minimum ``padding'' or ``separation'' between the border
    of nodes connected by an edge. Thus, if nodes are so big that nodes
    with a distance of |node distance| would overlap (or
    just come with \meta{dimension} distance of one another), their
    distance is enlarged so that this distance is still satisfied.
    The |pre| means that the padding is added to the node ``at the
    front''. This make sense only for some algorithms, like for a
    simple necklace layout.
  "]],
  examples = {[["
    \tikz \graph [simple necklace layout, node distance=0cm, nodes={circle,draw}]
      { 1--2--3--4--5--1 };
  "]],[["
    \tikz \graph [simple necklace layout, node distance=0cm, node sep=0mm,
                  nodes={circle,draw}]
      { 1--2--3[node pre sep=5mm]--4--5[node pre sep=1mm]--1 };
  "]]
  }
}

---

declare {
  key = "node post sep",
  type = "length",
  initial = ".333em",

  summary = [["
    Works like |node pre sep|.
  "]]
}



---
-- @param length A length.

declare {
  key = "node sep",
  type = "length",
  use = {
    { key = "node pre sep",  value = function(v) return v/2 end },
    { key = "node post sep", value = function(v) return v/2 end },
  },
  summary = [["
    A shorthand for setting both |node pre sep| and |node post sep| to
    $\meta{length}/2$.
  "]]
}


---

declare {
  key = "level distance",
  type = "length",
  initial = "1cm",

  summary = [["
    This is minimum distance that the centers of nodes on one
    level should have from the centers of nodes on the next level. It
    will not always be possible to satisfy this desired distance, for
    instance in case the nodes are too big. In this case, the
    \meta{length} is just considered as a lower bound.
  "]],
  examples = [["
    \begin{tikzpicture}[inner sep=2pt]
      \draw [help lines] (0,0) grid (3.5,2);
      \graph [layered layout, level distance=1cm, level sep=0]
        { 1 [x=1,y=2] -- 2 -- 3 -- 1 };
      \graph [layered layout, level distance=5mm, level sep=0]
        { 1 [x=3,y=2] -- 2 -- 3 -- 1, 3 -- {4,5} -- 6 -- 3 };
    \end{tikzpicture}
  "]]
}

---
declare {
  key = "layer distance",
  type = "length",
  use = {
    { key = "level distance", value = lib.id },
  },
  summary = "An alias for |level distance|"
}

---
declare {
  key = "level pre sep",
  type = "length",
  initial = ".333em",

  summary = [["
    This is a minimum ``padding'' or ``separation'' between the border
    of the nodes on a level to any nodes on the previous level. Thus, if
    nodes are so big that nodes on consecutive levels would overlap (or
    just come with \meta{length} distance of one another), their
    distance is enlarged so that this distance is still satisfied.
    If a node on the previous level also has a |level post sep|, this
    post padding and the \meta{dimension} add up. Thus, these keys
    behave like the ``padding'' keys rather
    than the ``margin'' key of cascading style sheets.
  "]],
  examples = [["
    \begin{tikzpicture}[inner sep=2pt, level sep=0pt, sibling distance=0pt]
      \draw [help lines] (0,0) grid (3.5,2);
      \graph [layered layout, level distance=0cm, nodes=draw]
        { 1 [x=1,y=2] -- {2,3[level pre sep=1mm],4[level pre sep=5mm]} -- 5 };
      \graph [layered layout, level distance=0cm, nodes=draw]
        { 1 [x=3,y=2] -- {2,3,4} -- 5[level pre sep=5mm] };
    \end{tikzpicture}
  "]]
}

---

declare {
  key = "level post sep",
  type = "length",
  initial = ".333em",

  summary = [["
    Works like |level pre sep|.
  "]]
}

---
declare {
  key = "layer pre sep",
  type = "length",
  use = {
    { key = "level pre sep", value = lib.id },
  },
  summary = "An alias for |level pre sep|."
}

---
declare {
  key = "layer post sep",
  type = "length",
  use = {
    { key = "level post sep", value = lib.id },
  },
  summary = "An alias for |level post sep|."
}




---
-- @param length A length

declare {
  key = "level sep",
  type = "length",
  use = {
    { key = "level pre sep", value = function (v) return v/2 end },
    { key = "level post sep", value = function (v) return v/2 end },
  },

  summary = [["
    A shorthand for setting both |level pre sep| and |level post sep| to
    $\meta{length}/2$. Note that if you set |level distance=0| and
    |level sep=1em|, you get a layout where any two consecutive layers
    are ``spaced apart'' by |1em|.
  "]]
}


---
declare {
  key = "layer sep",
  type = "number",
  use = {
    { key = "level sep", value = lib.id },
  },
  summary = "An alias for |level sep|."
}


---
declare {
  key = "sibling distance",
  type = "length",
  initial = "1cm",

  summary = [["
    This is minimum distance that the centers of node should have to the
    center of the next node on the same level. As for levels, this is
    just a lower bound.
    For some layouts, like a simple necklace layout, the \meta{length} is
    measured as the distance on the circle.
  "]],
  examples = {[["
    \tikz \graph [tree layout, sibling distance=1cm, nodes={circle,draw}]
      { 1--{2,3,4,5} };
  "]],[["
    \tikz \graph [tree layout, sibling distance=0cm, sibling sep=0pt,
                  nodes={circle,draw}]
      { 1--{2,3,4,5} };
  "]],[["
    \tikz \graph [tree layout, sibling distance=0cm, sibling sep=0pt,
                  nodes={circle,draw}]
      { 1--{2,3[sibling distance=1cm],4,5} };
  "]]
  }
}


---

declare {
  key = "sibling pre sep",
  type = "length",
  initial = ".333em",

  summary = [["
    Works like |level pre sep|, only for siblings.
  "]],
  examples = [["
    \tikz \graph [tree layout, sibling distance=0cm, nodes={circle,draw},
                  sibling sep=0pt]
      { 1--{2,3[sibling pre sep=1cm],4,5} };
  "]]
}

---

declare {
  key = "sibling post sep",
  type = "length",
  initial = ".333em",

  summary = [["
      Works like |sibling pre sep|.
   "]]
 }



---
--  @param length A length

declare {
  key = "sibling sep",
  type = "length",
  use = {
    { key = "sibling pre sep", value = function(v) return v/2 end },
    { key = "sibling post sep", value = function(v) return v/2 end },
  },

  summary = [["
    A shorthand for setting both |sibling pre sep| and |sibling post sep| to
    $\meta{length}/2$.
  "]]
}






---
declare {
  key = "part distance",
  type = "length",
  initial = "1.5cm",

  summary = [["
    This is minimum distance between the centers of ``parts'' of a
    graph. What a ``part'' is depends on the algorithm.
  "]]
}


---

declare {
  key = "part pre sep",
  type = "length",
  initial = "1em",
  summary = "A pre-padding for parts."
}

---

declare {
  key = "part post sep",
  type = "length",
  initial = "1em",
  summary = "A post-padding for pars."
 }



---
--  @param length A length

declare {
  key = "part sep",
  type = "length",
  use = {
    { key = "part pre sep", value = function(v) return v/2 end },
    { key = "part post sep", value = function(v) return v/2 end },
  },

  summary = [["
    A shorthand for setting both |part pre sep| and |part post sep| to
    $\meta{length}/2$.
  "]]
}




---

declare {
  key = "component sep",
  type = "length",
  initial = "1.5em",

  summary = [["
    This is padding between the bounding boxes that nodes of different
    connected components will have when they are placed next to each
    other.
  "]],
  examples = {[["
    \tikz \graph [binary tree layout, sibling distance=4mm, level distance=8mm,
                  components go right top aligned,
                  component sep=1pt, nodes=draw]
    {
      1 -> 2 -> {3->4[second]->5,6,7};
      a -> b[second] -> c[second] -> d -> e;
      x -> y[second] -> z -> u[second] -> v;
    };
  "]],[["
    \tikz \graph [binary tree layout, sibling distance=4mm, level distance=8mm,
                  components go right top aligned,
                  component sep=1em, nodes=draw]
    {
      1 -> 2 -> {3->4[second]->5,6,7};
      a -> b[second] -> c[second] -> d -> e;
      x -> y[second] -> z -> u[second] -> v;
    };
  "]]
  }
}



---

declare {
  key = "component distance",
  type = "length",
  initial = "2cm",

  summary = [["
    This is the minimum distance between the centers of bounding
    boxes of connected components when they are placed next to each
    other. (Not used, currently.)
  "]]
}


return Distances