Debian Codegraph @

texmf-dist/doc/latex/spath3/knots.tex

raw
1 %\immediate\write18{tex spath3_code.dtx}
2 \documentclass{ltxdoc}
3 \usepackage[T1]{fontenc}
4 \usepackage{trace}
5 \usepackage{lmodern}
6 \usepackage{morefloats}
7 \usepackage{tikz}
8 \usetikzlibrary{knots,spath3,hobby}
9 \usepackage[numbered]{hypdoc}
10 \definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9}
11
12 \usepackage{listings}
13 \lstloadlanguages{[LaTeX]TeX}
14 \lstset{
15 breakatwhitespace=true,
16 breaklines=true,
17 language=[LaTeX]TeX,
18 basicstyle=\small\ttfamily,
19 keepspaces=true,
20 columns=fullflexible
21 }
22
23 \usepackage{fancyvrb}
24
25 \newenvironment{example}
26 {\VerbatimEnvironment
27 \begin{VerbatimOut}{example.out}}
28 {\end{VerbatimOut}
29 \begin{center}
30 \setlength{\parindent}{0pt}
31 \fbox{\begin{minipage}{.9\linewidth}
32 \lstinputlisting[]{example.out}
33 \end{minipage}}
34
35 \fbox{\begin{minipage}{.9\linewidth}
36 \centering
37 \input{example.out}
38 \end{minipage}}
39 \end{center}
40 }
41
42 \providecommand*{\url}{\texttt}
43 \GetFileInfo{spath3.sty}
44
45 \pdfstringdefDisableCommands{%
46 \def\\{}%
47 \def\url#1{<#1>}%
48 }
49
50 \title{The \textsf{knots} Package: Documentation}
51 \author{Andrew Stacey \\ \url{[email protected]}}
52 \date{\fileversion~from \filedate}
53
54 \begin{document}
55
56 \maketitle
57
58 \section{Pre-Introduction}
59
60 This library is built on top of a package for manipulating PGF's \emph{soft paths} called \texttt{spath3}.
61 Version 2.0 of \texttt{spath3} involved considerable reorganisation of the code.
62 I tried to ensure that this didn't affect this library but it is extremely likely that I wasn't fully successful.
63 If something that used to work no longer does, please do let me know either by opening an issue on github (\url{https://github.com/loopspace/spath3}) or at the above email.
64
65 That version of \texttt{spath3} also introduced an alternative way of drawing knots which involves breaking the paths at their crossing points and introducing actual gaps.
66 This makes it easier to do things like have the knots on non-uniform backgrounds, and to style different parts of the knot differently such as illustrating a \(3\)--colouring.
67 To see how that works, look at the documentation of the \texttt{spath3} TikZ library.
68 Here's an example of how to draw a knot with that library.
69
70 \begin{example}
71 \begin{tikzpicture}[
72 use Hobby shortcut,
73 every trefoil component/.style={ultra thick, draw},
74 trefoil component 1/.style={red},
75 trefoil component 2/.style={blue},
76 trefoil component 3/.style={green},
77 ]
78 \path[spath/save=trefoil] ([closed]90:2) foreach \k in {1,...,3} { .. (-30+\k*240:.5) .. (90+\k*240:2) } (90:2);
79 \tikzset{spath/knot={trefoil}{8pt}{1,3,5}}
80 \end{tikzpicture}
81 \end{example}
82
83
84 \section{Introduction}
85
86 The \Verb+knots+ package is a TikZ library for drawing knot (and similar) diagrams.
87 It provides a few useful styles and node shapes but its main contribution is the \Verb+knot+ environment.
88 The \Verb+knot+ environment allows you to draw some strands of a knot (or braid or tangle or whatever -- we shall use the imprecise term ``knot'' to refer to any similar diagram) and then to modify the crossings via a simple interface.
89
90 The main part of this package was developed in response to a question on the \href{http://tex.stackexchange.com}{TeX-SX} site by Jamie Vicary.
91 The original question was \href{http://tex.stackexchange.com/q/32125/86}{Braid diagrams in TikZ}.
92 Jamie's comment (quoted below) was the inspiration for the mechanism of the \Verb+knot+ environment.
93
94 \begin{quotation}
95 [It] would be really cool if it was possible to draw the curves, let TikZ calculate all the intersection points automatically, and then tell it to redraw the intersections according to an under/over specification... do you think this is in the realm of plausibility?
96 \end{quotation}
97
98 \section{Examples}
99
100 Let us begin with an example.
101 To use the library, simply load the \Verb+tikz+ package and add \Verb+knots+ to the list of TikZ libraries that you load.
102 For example, the following in your preamble would work:
103
104 \begin{verbatim}
105 \usepackage{tikz}
106 \usetikzlibrary{knots}
107 \end{verbatim}
108
109 Let's draw a simple tangle (actually a braid).
110
111 \begin{example}
112 \begin{tikzpicture}
113 \draw[red,ultra thick] (0,0) .. controls +(1,0) and +(-1,0) .. (2,1) .. controls +(1,0) and +(-1,0) .. (4,0);
114 \draw[blue,ultra thick] (0,1) .. controls +(1,0) and +(-1,0) .. (2,0) .. controls +(1,0) and +(-1,0) .. (4,1);
115 \end{tikzpicture}
116 \end{example}
117
118 Now a common way to draw crossings for knots is to draw a gap in the under strand through which the over strand passes.
119 One way to achieve this in TikZ is to draw the over strand twice, the first time with a thicker line width and the colour of the background.
120 We'll draw it twice, once with background a different colour to illustrate this.
121
122 \begin{example}
123 \begin{tikzpicture}
124 \draw[red,ultra thick] (0,0) .. controls +(1,0) and +(-1,0) .. (2,1) .. controls +(1,0) and +(-1,0) .. (4,0);
125 \draw[pink,double=blue,ultra thick,double distance=1.6pt] (0,1) .. controls +(1,0) and +(-1,0) .. (2,0) .. controls +(1,0) and +(-1,0) .. (4,1);
126 \draw[xshift=5cm,red,ultra thick] (0,0) .. controls +(1,0) and +(-1,0) .. (2,1) .. controls +(1,0) and +(-1,0) .. (4,0);
127 \draw[xshift=5cm,white,double=blue,ultra thick,double distance=1.6pt] (0,1) .. controls +(1,0) and +(-1,0) .. (2,0) .. controls +(1,0) and +(-1,0) .. (4,1);
128 \end{tikzpicture}
129 \end{example}
130
131 Now the problem with this method is that there is no way to draw the red and blue paths so that the blue is the over strand at the first crossing and the red at the second.
132 Either the blue path is always on top (as shown) or the red.
133 One way to resolve this is to split the paths and draw one of them in segments:
134
135 \begin{example}
136 \begin{tikzpicture}
137 \draw[red,ultra thick] (0,0) .. controls +(1,0) and +(-1,0) .. (2,1);
138 \draw[white,double=blue,ultra thick,double distance=1.6pt] (0,1) .. controls +(1,0) and +(-1,0) .. (2,0) .. controls +(1,0) and +(-1,0) .. (4,1);
139 \draw[white,double=red,double distance=1.6pt,ultra thick] (2,1) .. controls +(1,0) and +(-1,0) .. (4,0);
140 \end{tikzpicture}
141 \end{example}
142
143 Another method (employed by the \Verb+braids+ package) is to break the under path either side of the crossing and not draw it there.
144 This means that the order of drawing doesn't matter.
145
146 Both of these methods have their drawbacks (particularly for general knots as opposed to the more structured braids) in that they require a detailed knowledge of the pieces of the paths and the positions of the crossings.
147 As pointed out by Jamie Vicary in the above-{}quoted comment, TikZ should be able to compute these itself.
148
149 That's what this package does.
150
151 Let's do the above example using this package.
152 The main changes to the drawing are that we use the command \Verb+\strand+ rather than \Verb+\draw+ and we enclose it in the \Verb+knot+ environment.
153 When initially drawing the strands it is useful to provide the option \Verb+draft mode=strands+.
154 That's because the detailed computation can take a little time and so it is best only to do it when necessary.
155 So on first run through we get the following.
156
157 \begin{example}
158 \begin{tikzpicture}
159 \begin{knot}[
160 draft mode=strands
161 ]
162 \strand[red,thick] (0,0) .. controls +(1,0) and +(-1,0) .. (2,1) .. controls +(1,0) and +(-1,0) .. (4,0);
163 \strand[blue,thick] (0,1) .. controls +(1,0) and +(-1,0) .. (2,0) .. controls +(1,0) and +(-1,0) .. (4,1);
164 \end{knot}
165 \end{tikzpicture}
166 \end{example}
167
168 Once we're happy with the positioning of the strands, we change the option \Verb+draft mode=strands+ to \Verb+draft mode=crossings+.
169
170 \begin{example}
171 \begin{tikzpicture}
172 \path (2,1.5) (2,-.5);
173 \begin{knot}[
174 draft mode=crossings,
175 clip width=5,
176 ]
177 \strand[red,ultra thick] (0,0) .. controls +(1,0) and +(-1,0) .. (2,1) .. controls +(1,0) and +(-1,0) .. (4,0);
178 \strand[blue,ultra thick] (0,1) .. controls +(1,0) and +(-1,0) .. (2,0) .. controls +(1,0) and +(-1,0) .. (4,1);
179 \end{knot}
180 \end{tikzpicture}
181 \end{example}
182
183 The \Verb+\path (2,1.5) (2,-.5);+ is to extend the bounding box of the picture a little upwards.
184 The extra pieces are not used when computing the bounding box of the picture so that it doesn't change position on the page.
185
186 The extra information is that the strands and the crossings have been numbered.
187 The crossings have also been rendered (the \Verb+clip width+ option enlarges the crossing gap to make it more obvious).
188 Unfortunately, for both crossings the red path is on top.
189 We need to flip one of these crossings (the first).
190 To do this, we either use the command \Verb+flipcrossings+ or the \Verb+flip crossing+ key.
191
192 \begin{example}
193 \begin{tikzpicture}
194 \path (2,1.5) (2,-.5);
195 \begin{knot}[
196 draft mode=crossings,
197 clip width=5,
198 flip crossing=1,
199 ]
200 \strand[red,ultra thick] (0,0) .. controls +(1,0) and +(-1,0) .. (2,1) .. controls +(1,0) and +(-1,0) .. (4,0);
201 \strand[blue,ultra thick] (0,1) .. controls +(1,0) and +(-1,0) .. (2,0) .. controls +(1,0) and +(-1,0) .. (4,1);
202 \end{knot}
203 \end{tikzpicture}
204 \end{example}
205
206 Once we're happy with it, we remove the \Verb+draft mode+ option to render it in its final form.
207
208 \begin{example}
209 \begin{tikzpicture}
210 \begin{knot}[
211 clip width=5,
212 flip crossing=1,
213 ]
214 \strand[red,ultra thick] (0,0) .. controls +(1,0) and +(-1,0) .. (2,1) .. controls +(1,0) and +(-1,0) .. (4,0);
215 \strand[blue,ultra thick] (0,1) .. controls +(1,0) and +(-1,0) .. (2,0) .. controls +(1,0) and +(-1,0) .. (4,1);
216 \end{knot}
217 \end{tikzpicture}
218 \end{example}
219
220 Here's a more complicated example.
221
222 \begin{example}
223 \begin{tikzpicture}
224 \node (A) at (0,4) [draw,minimum width=30pt,minimum height=10pt,thick] {};
225 \begin{knot}[
226 clip width=5,
227 clip radius=8pt,
228 ]
229 \strand [thick,only when rendering/.style={dashed}] (0,0)
230 to [out=up, in=down] (-1,1)
231 to [out=up, in=down] (0,2)
232 to [out=up, in=down] (-1.2,4)
233 to [out=up, in=down, looseness=0.7] (0,5.5)
234 to [out=up, in=down] (-2,7);
235 \strand [thick] (-1,0)
236 to [out=up, in=down] (1,2)
237 to [out=up, in=down] (A.south);
238 \strand [thick,blue] (1,0)
239 to [out=up, in=down] (-1,2)
240 to [out=up, in=down] (1.5,4)
241 to [out=up, in=right] (0,5.5)to [out=left, in=up] (-2,4)
242 to [out=down, in=up] (-2,0);
243 \strand [thick] (A.150)
244 to [out=up, in=down] (0.7,5.5)
245 to [out=up, in=down] (0,7);
246 \strand [thick] (A.30)
247 to [out=up, in=down] (-1,6)
248 to [out=up, in=down] (2,7);
249 \flipcrossings{6,2,9,5,11}
250 \end{knot}
251 \end{tikzpicture}
252 \end{example}
253
254 One feature about this example is the \Verb+only when rendering+ key.
255 The gaps are made by drawing the strand again with extra thickness in the background colour.
256 If the \Verb+dashed+ option were always in play for that strand, the gap would be dashed which would spoil the effect.
257 So the \Verb+only when rendering+ key gathers those options (such as a dash pattern) which should only be applied to the rendered strand and not to the redraw that creates the gap.
258
259 Here's another example.
260
261 \begin{example}
262 \newcommand{\motif}[1]{
263 to ++(180+#1:0.50) arc (270+#1:150+#1:0.15)
264 to ++( 60+#1:0.50) arc (-30+#1:150+#1:0.15)
265 to ++(240+#1:0.25) arc (150+#1:330+#1:0.25)
266 to ++( 60+#1:0.55) arc (150+#1: 30+#1:0.20)
267 }
268 \newcommand{\celticknot}{\motif{0}\motif{120}\motif{240}}
269 \begin{tikzpicture}
270 \begin{knot}[
271 line width=2pt,
272 line join=round,
273 clip width=2,
274 scale=5,
275 consider self intersections,
276 ignore endpoint intersections=false,
277 background color=white,
278 only when rendering/.style={
279 draw=red,
280 double=white,
281 double distance=6pt,
282 line cap=round,
283 }
284 ]
285 \strand (0,0) \celticknot;
286 \flipcrossings{1,3,6,8,10}
287 \end{knot}
288 \end{tikzpicture}
289 \end{example}
290
291 In this case the strand is a single path.
292 In the standard case crossings are only considered between separate strands (since the algorithm used by TikZ means that a strand intersects itself infinitely often).
293 The key \Verb+consider self intersections+ gets round this by ``exploding'' the strand into segments and considering each as a separate path with regard to finding the intersections.
294
295 A path consists of a series of lines and B\'ezier cubics.
296 The ``explosion'' of a path uses this decomposition.
297 Unfortunately, even that is not always enough as it is possible for a B\'ezier cubic to self-intersect.
298 The \Verb+consider self intersections+ also splits these B\'ezier curves in two to ensure that this doesn't happen\footnote{Computing when this is strictly necessary is difficult so it splits more than it needs to to ensure that enough are done.}.
299 To disable this, use the \Verb+consider self intersections=no splits+ option.
300 This is the recommended option.
301
302 \begin{example}
303 \begin{tikzpicture}
304 \begin{knot}[
305 consider self intersections,
306 draft mode=crossings,
307 ]
308 \strand (0,0) .. controls +(3,1) and +(-3,1) .. (1,0);
309 \end{knot}
310 \begin{knot}[
311 xshift=3cm,
312 consider self intersections=no splits,
313 draft mode=crossings,
314 ]
315 \strand (0,0) .. controls +(3,1) and +(-3,1) .. (1,0);
316 \end{knot}
317 \end{tikzpicture}
318 \end{example}
319
320 Finally, given that TikZ has to do some heavy computation to find the intersections, it is worth considering using the \Verb+external+ library of TikZ to avoid having to do this on every run.
321
322 \section{Usage}
323
324 \subsection{The \texttt{knot} Environment}
325
326 \DescribeMacro{knot}
327 \DescribeMacro{\strand}
328 This package provides a \Verb+knot+ environment for including in a \Verb+tikzpicture+ to render a knot.
329 This takes an optional argument which is passed to \Verb+\tikzset+ and can be used to configure the knot.
330 Within that environment, specific strands are defined using the \Verb+\strand+ command (in place of a \Verb+\path+ or \Verb+\draw+).
331 Further keys can be specified on the strands.
332
333 \DescribeMacro{flip crossing}
334 \DescribeMacro{\flipcrossings}
335 Specifying the crossings to be flipped can be done either using the key \Verb+flip crossing+ or the macro \Verb+\flipcrossings+.
336 The latter can take a comma separated list of crossings to flip.
337 The former takes a single crossing but can be extended to a comma separated list using the \Verb+.list+ handler as in \Verb+flip crossing/.list={1,2,3}+ (this is what \Verb+\flipcrossings+ does internally).
338
339 \DescribeMacro{\redraw}
340 There is also a macro \Verb+\redraw+ which redraws a strand in the neighbourhood of a point.
341 This is effectively what happens for the crossings and can be used to fix something that wasn't done correctly by the main algorithm.
342 It takes two arguments, the strand number and the point at which to render the strand, as in \Verb+\redraw{2}{(1,1)}+.
343
344 \subsection{Keys}
345
346 The various keys are as follows.
347 The majority of the keys are in the \Verb+/tikz/knot diagram+ family, but it does its best to pass unknown keys down to \Verb+/tikz/+.
348 The keys processed by the \Verb+knot+ environment are automatically in this family but the keys processed by the \Verb+\strand+ command are not.
349 If a standard key (in the option to the \Verb+knot+ environment) doesn't work, try prefixing it with \Verb+/tikz/+ or \Verb+/pgf/+.
350
351 \begin{itemize}
352 \item \DescribeMacro{every knot diagram}
353 The style \Verb+every knot diagram+ is executed at the start of the \Verb+knot+ environment.
354
355 Note that it is inside the \Verb+knot diagram+ family so if setting it outside (say, in the preamble) use \Verb+\tikzset{knot diagram/every knot diagram}+.
356
357 \item \DescribeMacro{name}
358 The crossings of a knot are given coordinates of the form \Verb+<name> <number>+.
359 The default name is \Verb+knot+.
360 The \Verb+name+ key renames it.
361
362 \item \DescribeMacro{every strand}
363 The contents of \Verb+every strand+ are applied to every strand.
364 By default this contains the \Verb+draw+ key so if resetting it you should probably ensure that it still has the \Verb+draw+ key.
365
366 Note that it is inside the \Verb+knot diagram+ family so if setting it outside (say, in the preamble) use \Verb+\tikzset{knot diagram/every knot diagram}+.
367
368 \item \DescribeMacro{only when rendering}
369 The key \Verb+only when rendering={<style>}+ is applied to the strand only when it is actually drawn and not when it is used to cut out part of the underlying path.
370
371 Note that there are actually two versions of this key: one in the \Verb+knot diagram+ family and one in the \Verb+/tikz+ family.
372 This is so that it works equally well in the argument to the \Verb+knot+ environment and the \Verb+\strand+ command.
373
374 \item \DescribeMacro{ignore endpoint intersections}
375 When a strand is split into pieces then the intersection library finds ``false positives'' in that neighbouring pieces intersect at their endpoints.
376 The code ignores such intersections between neighbouring pieces.
377 The \Verb+ignore endpoint intersections+ (which is true by default) means that all intersections that are near an endpoint are ignored whether or not they are with the next or previous piece of that strand.
378 The celtic knot example of the previous section sets this to false to ensure that it gets all intersections.
379
380 \item \DescribeMacro{consider self intersections}
381 The key \Verb+consider self intersections=<option>+ handles the splitting facility so that strands can self intersect.
382 The options are \Verb+true+, \Verb+false+, and \Verb+no splits+.
383 It is \Verb+false+ at the start, and the default option is \Verb+true+.
384 The difference between \Verb+true+ and \Verb+no splits+ is as to whether segments are further split to avoid \emph{all} self intersections.
385
386 \item \DescribeMacro{clip radius}
387 The \Verb+clip radius=<length>+ is the radius of the clip region around each crossing.
388
389 \item \DescribeMacro{end tolerance}
390 The \Verb+end tolerance=<length>+ is the distance at which an intersection is considered as being near an endpoint (for simplicity, it uses the \(\ell^1\)--metric).
391
392 \item \DescribeMacro{clip width}
393 The \Verb+clip width=<factor>+ is the multiplier for the thickness of the ``wipeout'' path relative to the line width of the actual path.
394
395 \item \DescribeMacro{flip crossing}
396 The \Verb+flip crossing=<number>+ key flips the \Verb+<number>+ crossing.
397
398 \item \DescribeMacro{background colour} \DescribeMacro{background color}
399 The keys \Verb+background colour=<colour>+ and \Verb+background color=<color>+ set the background colour for the crossings.
400
401 \item \DescribeMacro{every intersection>} \DescribeMacro{intersection <number>}
402 The style in \Verb+every intersection+ is applied before rendering each crossing, with \Verb+intersection <number>+ applied just before that specific crossing.
403 These can be used to change how the over-strands are rendered when they are redrawn.
404 For an example on using \Verb+every intersection+, see Section~\ref{sec:celtic}.
405
406
407 \item \DescribeMacro{draft mode}
408 The key \Verb+draft mode=<option>+ sets the different styles for aiding with rendering the knot.
409 The options are \Verb+strands+, \Verb+crossings+, or \Verb+off+.
410 The \Verb+strands+ option just renders the strands with no crossings.
411 The \Verb+crossings+ option renders the crossings and labels the strands and crossings.
412 The \Verb+off+ option renders the crossings without the labels.
413
414 \item \DescribeMacro{draft/crossing label}
415 The style \Verb+draft/crossing label+ is applied to each of the crossing labels.
416 The labels are actually \Verb+pin+s attached to coordinates at the crossings.
417 This style is applied to the \Verb+pin+ itself.
418 The default is:
419
420 \begin{lstlisting}
421 overlay,
422 fill=white,
423 fill opacity=.5,
424 text opacity=1,
425 text=blue,
426 pin edge={blue,<-}
427 \end{lstlisting}
428
429 \item \DescribeMacro{draft/strand label}
430 The style \Verb+draft/strand label+ is applied to each of the strand labels.
431 The default is:
432
433 \begin{lstlisting}
434 overlay,
435 circle,
436 draw=purple,
437 fill=white,
438 fill opacity=.5,
439 text opacity=1,
440 text=purple,
441 inner sep=0pt
442 \end{lstlisting}
443 \end{itemize}
444
445
446 \subsection{Celtic Knots}
447 \label{sec:celtic}
448
449 By ``Celtic knot'' here, I mean a knot drawn in a way to suggest a carved object.
450 Usually, this is achieved by using the \Verb+double+ style to outline the path.
451 This interacts a little oddly with how the knots package redraws the curve near crossings which can result in small artefacts visible when the diagram is viewed (my understanding is that they are not present when the diagram is printed).
452 There is, however, a way to get these diagrams right, as this section will show.
453
454 I will just note here that there is the \href{celtic knots}{https://ctan.org/pkg/celtic} package which works for a particular type of Celtic knots.
455 If your Celtic knot fits what that package can produce, it is a better choice.
456 See that package for details.
457
458 Back to what this package can provide.
459 When rendering a crossing, the over-strand is redrawn clipped to a small region around the crossing.
460 The clipping, however, interacts badly with the \Verb+double+ effect.
461 The \Verb+double+ effect is achieved by drawing the line twice, once thicker with the outer colour and once thinner with the inner colour.
462 At the boundary of the clipping region there is ``bleed through'' of the outer colour into the inner colour, at least when the image is displayed on a screen.
463 If the inner colour is darker, this is not noticeable.
464 But with a Celtic style knot then the inner colour is usually a lighter colour, such as the page colour, and so the effect is visible.
465
466 The solution to this is to exploit the fact that when using the Celtic style then one doesn't actually want gaps in the under-strand to show that it is the under-strand.
467 The Celtic style makes it very obvious which strand is which without that.
468 These gaps are achieved by drawing the over-strand in a thicker line with the colour of the background.
469 This is almost exactly what the \Verb+double+ key does.
470 So rather than using the \Verb+double+ key directly, we use the mechanism of how the knot crossings are rendered to reproduce the effect.
471 This avoids the artefacts because when the knot library draws the two paths then it clips them to slightly different sized regions.
472
473 \begin{example}
474 \begin{tikzpicture}[scale=0.8]
475 \begin{knot}[
476 consider self intersections=no splits,
477 end tolerance=1pt,
478 line join=round,
479 clip width=1,
480 ignore endpoint intersections=true,
481 background color=red,
482 every intersection/.style={
483 line width=13pt,
484 only when rendering/.style={
485 draw=white,
486 line width=9pt,
487 double=none,
488 }
489 },
490 only when rendering/.style={
491 red,
492 line width=2pt,
493 double=white,
494 double distance=9pt,
495 },
496 flip crossing/.list={2,3,6,8}
497 ]
498
499 \strand
500 (0.5,1) to [out=north, in=south]
501 (2.5,4) to [out=north, in=south]
502 (0.5,7) -- (0.5,7) -- (0.5,7.5) --
503 (1,7.5) to [out=east, in=west]
504 (3,6.5) to [out=east, in=225]
505 (4.5,7.5) to [out=45, in=south]
506 (5.5,9) to [out=north, in=-45]
507 (4.5,10.5) to [out=135,in=east]
508 (3,11.5) to [out=west,in=45]
509 (1.5,10.5) to [out=225,in=north]
510 (0.5,9) -- (0.5,8.5) --
511 (1,8.5) to [out=east, in=south]
512 (2.5,10) to [out=north, in=east]
513 (1,11.5) -- (0.5,11.5) --
514 (0.5,11) to [out=south, in=north]
515 (2.5,8) to [out=south, in=north]
516 (0.5,5) -- (0.5,4.5) --
517 (1,4.5) to [out=east, in=west]
518 (3,5.5) to [out=east, in=135]
519 (4.5,4.5) to [out=-45, in=north]
520 (5.5,3) to [out=south, in=45]
521 (4.5,1.5) to [out=225, in=east]
522 (3,0.5) to [out=west, in=-45]
523 (1.5,1.5) to [out=135, in=south]
524 (0.5,3) -- (0.5,3.5) --
525 (1,3.5) to [out=east, in=north]
526 (2.5,2) to [out=south, in=east]
527 (1,0.5) -- (0.5,0.5) -- (0.5,1);
528 \end{knot}
529
530 \end{tikzpicture}
531
532 \end{example}
533
534
535
536
537
538
539 \subsection{Other Styles}
540
541 The other things defined by this package are for drawing knot diagrams when the user knows in advance either the locations of the crossings or can arrange that the paths are drawn in the correct order.
542 In these circumstances the \Verb+knot+ environment is overkill.
543
544 \DescribeMacro{knot}
545 \DescribeMacro{knot gap}
546 This \Verb+knot=<colour>+ style sets up a doubled path with inner colour the given colour (or the current draw colour if not given) and outer colour the knot background colour.
547 The width of the inner line is the current line width and the full width is controlled by the \Verb+knot gap=<factor>+ key which is initially set to \(3\) (thus giving a line's width either side).
548
549 \begin{example}
550 \begin{tikzpicture}[knot gap=7]
551 \draw[thin,knot=red] (-1,-1) -- (1,1);
552 \draw[thin,knot=red] (-1,1) -- (1,-1);
553 \begin{scope}[xshift=2.5cm]
554 \draw[knot=red] (-1,-1) -- (1,1);
555 \draw[knot=red] (-1,1) -- (1,-1);
556 \end{scope}
557 \begin{scope}[xshift=5cm]
558 \draw[thick,knot=red] (-1,-1) -- (1,1);
559 \draw[thick,knot=red] (-1,1) -- (1,-1);
560 \end{scope}
561 \end{tikzpicture}
562 \end{example}
563
564 \DescribeMacro{knot crossing}
565 \DescribeMacro{knot over cross}
566 \DescribeMacro{knot under cross}
567 \DescribeMacro{knot horiz}
568 \DescribeMacro{knot vert}
569 This package also defines some node shapes to help draw knot and link diagrams.
570 The idea with these is to place a node of the appropriate type at each crossing and then link them accordingly.
571 The node shapes are \Verb+knot crossing+, \Verb+knot over cross+, \Verb+knot under cross+, \Verb+knot vert+, \Verb+knot horiz+.
572 The two styles \Verb+knot over cross+ and \Verb+knot under cross+ are crossings, \Verb+knot vert+ and \Verb+knot horiz+ are for when resolving the crossings in a diagram.
573 By judicious use of the \Verb+\foreach+ command, a family of resolved link diagrams can be produced.
574
575 \begin{example}
576 \begin{tikzpicture}[every node/.style={draw,red}]
577 \node[knot over cross] at (1,0) {};
578 \node[knot under cross] at (2,0) {};
579 \node[knot vert] at (3,0) {};
580 \node[knot horiz] at (4,0) {};
581 \end{tikzpicture}
582 \end{example}
583
584 The node \Verb+knot crossing+ is not meant to be drawn, it is an empty shape.
585 Its value is in that it defines more anchors than the usual rectangle shape.
586 For each of the 8 main compass directions, it defines anchors at 2, 4, 8, 16, and 32 times further out.
587 This can be useful for designing curves that enter and exit the crossing gracefully at particular directions.
588 When using this node shape, the crossing itself is easiest to draw by using the \Verb+center+ anchor for the strands that form the over cross.
589
590 \begin{example}
591 \begin{tikzpicture}[every path/.style={red,thick}, every node/.style={transform shape, knot crossing, inner sep=1.5pt}]
592 \node[rotate=45] (tl) at (-1,1) {};
593 \node[rotate=-45] (tr) at (1,1) {};
594 \node (m) at (0,-1) {};
595 \node (b) at (0,-2) {};
596 \draw (b) .. controls (b.4 north west) and (m.4 south west) .. (m.center);
597 \draw (b.center) .. controls (b.4 north east) and (m.4 south east) .. (m);
598 \draw (m) .. controls (m.8 north west) and (tl.3 south west) .. (tl.center);
599 \draw (m.center) .. controls (m.8 north east) and (tr.3 south east) .. (tr);
600 \draw (tl.center) .. controls (tl.16 north east) and (tr.16 north west) .. (tr);
601 \draw (b) .. controls (b.16 south east) and (tr.16 north east) .. (tr.center);
602 \draw (b.center) .. controls (b.16 south west) and (tl.16 north west) .. (tl);
603 \draw (tl) -- (tr.center);
604 \end{tikzpicture}
605 \end{example}
606
607 \section{Other Relevant Packages by the Same Author}
608
609 Another tool for drawing knot diagrams is provided by the \Verb+hobby+ package which draws smooth curves through a prescribed set of points.
610 This can be combined with the facilities of this package but also has some features of its own that make it suitable for drawing knot diagrams.
611
612 For braids themselves, there is the \Verb+braids+ package which allows input specification in the form of a word in the braid group.
613
614 \section{Troubleshooting}
615
616 The diagrams drawn by this package can involve quite complicated calculations and they don't always turn out as expected.
617 There are plenty of \href{https://tex.stackexchange.com/search?q=knots}{questions on TeX-SX} about this package, but sifting through them can be tricky.
618 Through answering some of them, I've developed a few strategies for figuring out what's going on.
619 This section details some of what can go wrong and some of those strategies for finding out what's going on.
620
621 \subsection{Small Diagrams}
622
623 A common situation when the diagrams don't always work out is when the diagram is relatively small.
624 The defaults in this library are set for a diagram of a few centimetres across.
625 Some of the key properties are stored as dimensions which means that they don't naturally scale but have to be reset.
626 In particular, the \Verb!end tolerance! and \Verb!clip radius! are dimensions with defaults \Verb!14pt! and \Verb!10pt! respectively.
627
628 The \Verb!end tolerance! is used to weed out false intersections that occur when a strand is split into pieces.
629 Therefore, if the \Verb!consider self intersections! key is not set then \Verb!end tolerance! is largely unneeded (though it is still used) so can safely be set to something very small.
630
631 The effect of this can be seen in the following (where to make the issue evident, I've made \Verb!end tolerance! larger rather than make the diagram small).
632
633 \begin{example}
634 \begin{tikzpicture}
635 \begin{knot}[
636 end tolerance=1.5cm
637 ]
638 \strand[red] (0,0) to[out=0,in=180] ++(1,1);
639 \strand[blue] (0,1) to[out=0,in=180] ++(1,-1);
640 \end{knot}
641 \begin{knot}
642 \strand[red] (1.5,0) to[out=0,in=180] ++(1,1);
643 \strand[blue] (1.5,1) to[out=0,in=180] ++(1,-1);
644 \end{knot}
645 \end{tikzpicture}
646 \end{example}
647
648 The \Verb!clip radius! determines how much of the diagram is redrawn near a crossing.
649 If the crossings are very close together, the redraws can interfere with each other.
650
651 \begin{example}
652 \begin{tikzpicture}
653 \begin{knot}[
654 clip radius=.6cm,
655 flip crossing=2
656 ]
657 \strand[red] (0,0) to[out=0,in=180] ++(1,.6) to[out=0,in=180] ++(1,-.6);
658 \strand[blue] (0,1) to[out=0,in=180] ++(1,-.6) to[out=0,in=180] ++(1,.6);
659 \end{knot}
660 \begin{knot}[flip crossing=2]
661 \strand[red] (2.5,0) to[out=0,in=180] ++(1,.6) to[out=0,in=180] ++(1,-.6);
662 \strand[blue] (2.5,1) to[out=0,in=180] ++(1,-.6) to[out=0,in=180] ++(1,.6);
663 \end{knot}
664 \end{tikzpicture}
665 \end{example}
666
667 \subsection{Strategies}
668
669 \begin{itemize}
670 \item \Verb+draft mode=crossings+
671
672 This is useful to check that all the intersections are actually being found.
673 Any that aren't might be due to \Verb!end tolerance! being too large.
674 Or if \Verb!consider self intersections! is set to \Verb!no splits! then some self intersections might not be found.
675
676 \item \Verb+background clip+ and \Verb+clip+ styles.
677
678 When a crossing is redrawn, the over strand is clipped to a circle centred on the crossing.
679 First a background path is drawn to ``wipe out'' the under strand and then the over strand is drawn.
680 The clip circle for the background path is slightly smaller than the over path to avoid an issue whereby faint artefacts are visible (called \href{https://tex.stackexchange.com/q/188447/86}{crop circles} in one question on TeX-SX).
681 Rather than use a \Verb!\clip! directly, I use \Verb!\path[background clip]! and \Verb!\path[clip]! which means that these styles can be modified to show the region that is being used.
682 A useful style is:
683
684 \begin{lstlisting}
685 background clip/.append style={
686 preaction={
687 fill=gray,
688 fill opacity=.5,
689 }
690 }
691 \end{lstlisting}
692
693 \begin{example}
694 \begin{tikzpicture}
695 \begin{knot}[
696 clip radius=.6cm,
697 flip crossing=2,
698 background clip/.append style={
699 preaction={
700 fill=gray,
701 fill opacity=.5,
702 }
703 }
704 ]
705 \strand[red] (0,0) to[out=0,in=180] ++(1,.6) to[out=0,in=180] ++(1,-.6);
706 \strand[blue] (0,1) to[out=0,in=180] ++(1,-.6) to[out=0,in=180] ++(1,.6);
707 \end{knot}
708 \begin{knot}[
709 flip crossing=2,
710 background clip/.append style={
711 preaction={
712 fill=gray,
713 fill opacity=.5,
714 }
715 }
716 ]
717 \strand[red] (2.5,0) to[out=0,in=180] ++(1,.6) to[out=0,in=180] ++(1,-.6);
718 \strand[blue] (2.5,1) to[out=0,in=180] ++(1,-.6) to[out=0,in=180] ++(1,.6);
719 \end{knot}
720 \end{tikzpicture}
721 \end{example}
722
723
724 \end{itemize}
725
726
727 \end{document}
728 % Local Variables:
729 % tex-output-type: "pdf18"
730 % End: