Debian Codegraph @

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

raw
1 \RequirePackage{shellesc}
2 %\immediate\write18{tex spath3_code.dtx}
3 \documentclass{l3doc}
4 \usepackage{tikz}
5 \usetikzlibrary{
6 spath3,
7 hobby,
8 patterns,
9 intersections,
10 arrows.meta,
11 }
12
13 \usepackage{listings}
14 \lstloadlanguages{[LaTeX]TeX}
15 \lstset{
16 breakatwhitespace=true,
17 breaklines=true,
18 language=[LaTeX]TeX,
19 basicstyle=\small\ttfamily,
20 keepspaces=true,
21 columns=fullflexible
22 }
23
24 \usepackage{fancyvrb}
25
26 \newenvironment{example}
27 {\VerbatimEnvironment
28 \begin{VerbatimOut}[gobble=0]{example.out}}
29 {\end{VerbatimOut}
30 \begin{center}
31 \setlength{\parindent}{0pt}
32 \fbox{\begin{minipage}{.9\linewidth}
33 \lstinputlisting[]{example.out}
34 \end{minipage}}
35
36 \fbox{\begin{minipage}{.9\linewidth}
37 \centering
38 \input{example.out}
39 \end{minipage}}
40 \end{center}
41 }
42
43 \providecommand*{\url}{\texttt}
44 \GetFileInfo{spath3.sty}
45
46 \pdfstringdefDisableCommands{%
47 \def\\{}%
48 \def\url#1{<#1>}%
49 }
50
51 \title{The \textsf{spath3} Package: Documentation}
52 \author{Andrew Stacey \\ \url{[email protected]}}
53 \date{\fileversion~from \filedate}
54
55 \let\OriginalBar=|
56
57 \begin{document}
58
59 \maketitle
60
61 \tableofcontents
62
63 \section{Introduction}
64
65 The \texttt{spath3} package was originally designed as a low-level package for manipulating the \emph{soft paths} defined by PGF/TikZ.
66 Soft paths form one stage of the stack of translations between what the author writes in the \texttt{tikzpicture} environments in their \LaTeX\ document and what is eventually written to the output file.
67 Most of the complicated processing has been done by the time a soft path is constructed, but it is still very definitely a \TeX\ object and there has not, for example, been any consideration as to what the eventual output file format is (such as PDF, DVI, or SVG).
68 So it is very amenable to being modified at this stage and this package provides a set of routines for doing so.
69
70 The original purpose was to provide a common core on which other packages would be built.
71 Indeed, the packages \texttt{calligraphy}, \texttt{knots}, and \texttt{tilings} all use this package.
72 However, over time I've found myself wanting to use the routines of this package at a higher level and so have designed some user-level interfaces.
73 This document documents those.
74
75 To clarify some terminology used in this document (and more generally, this package), I regard paths as being composed of \emph{segments} and \emph{components}.
76 A \emph{segment} is a minimal drawing piece.
77 Thus it might be a straight line or a B\'ezier curve.
78 A \emph{component} is a minimal connected section of the path.
79 So every component starts with a move command and continues until the next move command.
80 For ease of implementation (and to enable a copperplate pen in the calligraphy package!), an isolated move is considered as a component.
81
82 There are no doubt bugs in this package, and useful things that I haven't implemented.
83 If you have found one of either of these, please let me know!
84 The best way is to open an issue at the code repository on github, at \href{https://github.com/loopspace/spath3}{https://github.com/loopspace/spath3}.
85
86
87 \section{TikZ Keys}
88
89 \begin{lstlisting}
90 \usetikzlibrary{spath3}
91 \end{lstlisting}
92
93 The \texttt{spath3} TikZ library defines a set of keys that can be issued to muck about with soft paths.
94 These are all defined in the |spath| family, so all the following keys should be prefixed by |spath/|, or the key |spath/.cd| needs to be used beforehand (but note that as yet I haven't implemented sending unknown keys back to the main |tikz| directory).
95
96 The keys try to gracefully fail if the path doesn't exist or is empty\footnote{A path that was defined inside a group will be empty if referred to outside that group rather than not existing.}.
97 The intention is that the document should still compile with a warning in the log file (and on the console output).
98 If this doesn't happen, please report it.
99
100 \subsection{Path Names}
101
102 Soft paths are stored in macros but are referred to via a name.
103 The macro is constructed from the name, but there is scope for a prefix and suffix.
104 By default, these are set up so to be compatible with the |intersections| library -- this package and that save their paths in the same underlying macro.
105 Some packages that are built on top of this one (such as the |knot| and |penrose| packages) install their own prefixes and suffixes to avoid clashes.
106
107 \begin{function}{
108 set prefix,
109 set suffix,
110 prefix,
111 suffix
112 }
113 \begin{syntax}
114 |set prefix=|\marg{prefix}
115 |set suffix=|\marg{suffix}
116 |prefix=|\oarg{name}
117 |suffix=|\oarg{name}
118 |set name=|\oarg{name}
119 \end{syntax}
120 The first two keys set the prefix and suffix directly.
121 The other keys allow for defining a label for a prefix and suffix for quick switching between different ones.
122 The default (with key |default| or no key specified) is to match the |intersections| library.
123 The |knots| library uses this to set a different prefix.
124 \end{function}
125
126 Using names rather than macros directly also makes it possible to link a soft path with a set of TikZ styles (this is particularly useful when splitting the path into components).
127
128 \begin{variable}{current}
129 \begin{syntax}
130 |\path (0,0) -- (3,0) to[out=90, in=90] (1,0) [spath/adjust and close=current];|
131 \end{syntax}
132
133 There is a special path name, |current|, which refers to the current path being built.
134 To be clear, the test for this name takes place before any prefix or suffix is applied so it depends only on what the user uses.
135
136 When this name is encountered, the current path is copied into a macro and that path is used in the command.
137 If the command is such that it is possible that the path is modified in some fashion then after the command is finished the old current path is replaced by the new one.
138 There are several commands that take multiple paths and |current| can be used in place of any of the paths, but usually there is only one that is modified and so that is the only one that would be used to replace the old current path.
139
140 It only makes sense to use it in a path-building context, and it refers to the path at the moment of invocation, so it doesn't do a lot in the main options on that path but it can be used in options later on in the process.
141
142 Sometimes it isn't possible to put commands partway through a path (for example, if the path command is buried in another macro) so there is a key which can be used to delay things to the end of the construction:
143
144 \begin{verbatim}
145 at end path construction={code}
146 \end{verbatim}
147 %
148 This invokes the |code| right after the path has finished being built.
149 \end{variable}
150
151 \subsection{Saving and Using Soft Paths}
152
153 \begin{function}{save, save global}
154 \begin{syntax}
155 |save=|\meta{name}
156 |save global=|\meta{name}
157 \end{syntax}
158
159 Saves the current path with name \meta{name}.
160 This delays until the path is fully constructed so can be issued in the options to the main command.
161
162 Soft paths constructed this way are local to the group in which the path command is issued.
163 The |global| version saves the path globally which is useful when the original path is inside a scope or even another tikzpicture.
164
165 If wanting to save the border of a node then because there are extra levels of grouping, the global version of this key has to be used.
166
167 \end{function}
168
169 \begin{function}{clone, clone globally}
170 \begin{syntax}
171 |clone=|\marg{target}\marg{source}
172 |clone globally=|\marg{target}\marg{source}
173 \end{syntax}
174
175 Clones one soft path into another.
176 In the second, the clone is global (the original need not be).
177
178 By using |current| as the source name, the current soft path in its current state is copied.
179 This can be used to get round the restriction whereby |save path| waits until the path is fully constructed before being saved.
180 \end{function}
181
182 \begin{function}{show, show current path}
183 \begin{syntax}
184 |show=|\meta{name}
185 |show current path|
186 \end{syntax}
187
188 These keys display a path on the terminal and in the log file.
189 They do a bit of sensible line formatting so that the paths are relatively easy to scan through.
190
191 The key |show current path| delays the logging until the path is fully constructed.
192 To get a view of what the path is at an intermediate stage of construction, use |show=current|.
193 \end{function}
194
195 \begin{function}{use}
196 \begin{syntax}
197 |use=|\meta{name}
198 |use=|\marg{name, options}
199 \end{syntax}
200
201 This uses a previously saved soft path at the current juncture in the path declaration.
202 If before the path has begun, it is the initial part of the new path.
203 If during the path construction then it is stuck in at the current place.
204 Note that any keys that affect the soft path directly should be applied \emph{before} this one.
205
206 The path can be modified first by using the second form -- note that as far as the \Verb+use+ key is concerned, the whole thing is a single argument.
207 The options is a comma separated list and can include:
208 %
209 \begin{itemize}
210 \item |reverse| reverses the inserted path first.
211 \item |weld|, |no weld| determines whether to weld the inserted path to the current path.
212 Welding means that the |move to| at the start of the inserted path is removed.
213 Note that this doesn't \emph{move} the inserted path so this will usually modify the first segment of the inserted path, possibly in unexpected ways.
214 The expected use is that when the |weld| key is used then the inserted path starts where the current path ends either because it already does or because the |move| key has also been invoked.
215 But there's nothing \emph{stopping} anyone using this key in other circumstances.
216 \item |move|, |no move| determines whether the inserted path is translated so that it starts where the current path ends.
217 \item |transform=|\marg{transformations} applies the specified transformations to the inserted path.
218 See the |transform| key in Section~\ref{sec:transform}.
219 \item |use current transformation| applies the current transformation to the inserted path.
220 Note that because the keys are processed and then acted upon, this key is always applied \emph{before} the |transform| key.
221 \item Any other key is taken as the name of the path (so it doesn't have to be specified first) with the last one winning.
222 \end{itemize}
223
224 One thing should be noted about transformations.
225 By the time a soft path is built, all available transformations have been applied.
226 This means that when re-inserting a soft path back into a high level command (such as |\draw|), existing transformations should have no effect (other than those specified via the |transform| key).
227 Where this gets a little tricky is with things like node placement -- using the \Verb+pos=D+ key on a node positions that node at a particular point on the path.
228 Exactly how the parameter is interpreted is the same as for the \Verb+spath+ coordinate system described in Section~\ref{sec:coordinates}.
229 When restoring a path then the library tries to set up various internals of TikZ correctly, but there may be some things I've overlooked or not accounted for particularly with regard to existing transformations; if you spot anything working oddly then please report it to me.
230 \end{function}
231
232 \begin{function}{
233 restore,
234 restore reverse
235 insert,
236 insert reverse,
237 append,
238 append reverse,
239 append no move,
240 append reverse no move
241 }
242
243 These are all aliases to various versions of \Verb+use+ (they originally existed as separate code before I united them all as variants of \Verb+use+).
244 The equivalences are:
245
246 \begin{itemize}
247 \item |restore| and |insert| are aliases for |use|.
248 \item |append| sets the |move| and |weld| keys.
249 \item |append no move| just sets the |weld| key.
250 \item |reverse| sets the |reverse| key.
251 \end{itemize}
252 \end{function}
253
254 \begin{function}{join with}
255 \begin{syntax}
256 |join with=|\marg{path}\marg{path, options}
257 \end{syntax}
258
259 This joins the second path to the first, with applying the specified options.
260 The options are the same as for the |use| key.
261 The first path is modified, the second is not (the second path is copied before any modifications are applied).
262
263 It is almost the case that |join with={current}{...}| is synonymous with |use={...}|.
264 The difference is that |use={...}| applies an extra check to ensure that the resulting path is not empty.
265 \end{function}
266
267 \begin{function}{to}
268 \begin{syntax}
269 |to=|\marg{name}
270 \end{syntax}
271
272 This defines a \Verb+to+ path from a soft path, so it inserts the soft path into the current path to span the gap between the start and end.
273 The path is transformed by rotation, translation, and uniform scaling so that it exactly spans the gap required by the \Verb+to+ syntax.
274 (If the start and end point of the soft path are very close together then it won't span the gap.)
275 \end{function}
276
277
278 \subsection{Transformation Routines}
279 \label{sec:transform}
280
281 The following keys all apply some sort of transformation to the soft path.
282 They do not render the path, but simply adjust it (but they can be used to modify the current path by invoking with the path name |current|).
283 The global versions apply their transformation globally, otherwise it is local to the current group (or scope).
284
285 \begin{function}{reverse, reverse global}
286 \begin{syntax}
287 |reverse=|\meta{name}
288 |reverse globally=|\meta{name}
289 \end{syntax}
290
291 Reverses the soft path in place.
292 If you want to use the original path and its reversal in the same path (for example, for constructing a region to fill) then use the \texttt{clone} key to copy it first.
293 \end{function}
294
295
296 \begin{function}{translate, translate global}
297 \begin{syntax}
298 |translate=|\marg{name}\marg{x-dimen}\marg{y-dimen}
299 |translate globally=|\marg{name}\marg{x-dimen}\marg{y-dimen}
300 \end{syntax}
301
302 Translates the soft path by the given dimensions.
303 \end{function}
304
305 \begin{function}{transform, transform global}
306 \begin{syntax}
307 |transform=|\marg{name}\marg{transformations}
308 |transform globally=|\marg{name}\marg{transformations}
309 \end{syntax}
310
311 This applies the transformation to the soft path.
312 The transformation is processed by TikZ so should consist of TikZ-level transformations such as |shift={(2,2)}|.
313 \end{function}
314
315 \begin{function}{span, span global}
316 \begin{syntax}
317 |span=|\marg{name}\marg{start point}\marg{end point}
318 |span globally=|\marg{name}\marg{start point}\marg{end point}
319 \end{syntax}
320
321 This transforms the named path so that it goes from the start point to the end point.
322 As with the \Verb+to+ path construction and the \Verb+splice+ method, this won't work if the path ends very close to where it starts.
323 \end{function}
324
325
326 \subsection{Intersection Routines}
327
328 To use these features you need to use the \texttt{intersections} library.
329
330 \begin{function}{
331 split at self intersections,
332 split globally at self intersections
333 }
334 \begin{syntax}
335 |split at self intersections=|\meta{path}
336 |split globally at self intersections=|\meta{path}
337 \end{syntax}
338
339 This inserts breaks into the named soft path at the points where it intersects itself.
340 The breaks are not gaps, to achieve that use the shortening routines after this, rather they are a change of component.
341 Think of it as if you took the pen off the page at that point and then put it straight back down again.
342 \end{function}
343
344 \begin{function}{
345 split at intersections with,
346 split globally at intersections with
347 }
348 \begin{syntax}
349 |split at intersections with=|\marg{first}\marg{second}
350 |split globally at intersections with=|\marg{first}\marg{second}
351 \end{syntax}
352
353 This inserts breaks into the first path where it intersects with the second.
354 The second path is not changed.
355 \end{function}
356
357 \begin{function}{
358 split at intersections,
359 split globally at intersections
360 }
361 \begin{syntax}
362 |split at intersections=|\marg{first}\marg{second}
363 |split globally at intersections=|\marg{first}\marg{second}
364 \end{syntax}
365
366 This inserts breaks into a pair of paths at their mutual intersections.
367 \end{function}
368
369 \begin{function}{
370 replace lines,
371 replace lines globally
372 }
373 \begin{syntax}
374 |replace lines=|\meta{path}
375 |replace lines globally=|\meta{path}
376 \end{syntax}
377
378 The PGF intersection routines have difficulties with parallel, or near parallel, lines.
379 One way to counter this is to replace all line segments by ``curves''.
380 This is done so that the parametrisation of the curve matches that of the line segment that it is replacing.
381 \end{function}
382
383 \subsection{Working with Components}
384
385 \begin{function}{
386 get components of,
387 get components of globally,
388 \getComponentOf
389 }
390 \begin{syntax}
391 |get components of=|\marg{path}\marg{macro}
392 |get components of globally=|\marg{path}\marg{macro}
393 |\getComponentOf|\marg{macro}\marg{number}
394 \end{syntax}
395
396 This splits the path into a list of its components, which are stored in the macro.
397 The macro can be used in a |\foreach|.
398
399 The macro consists of a comma separated list of names of the components (the actual names used are of the form \Verb+anonymous_N+).
400 To access an individual component, use the command \Verb+\getComponentOf+.
401 This can be used directly in place of a path name in any other key, such as \Verb+use+, (it is just the \LaTeX3 command \Verb+\clist_item:Nn+).
402
403 Note that these are \emph{copies} of the components of the original path.
404 Changing a component doesn't update the original path.
405 \end{function}
406
407 \begin{function}{render components}
408 \begin{syntax}
409 |render components=|\meta{path}
410 \end{syntax}
411
412 This renders the components of a given path as separate TikZ commands, so that each can be separately styled.
413 It applies the following styles (in this order):
414
415 \begin{enumerate}
416 \item \texttt{every spath component}
417 \item \texttt{spath component <number>}
418 \item \texttt{spath component=<number>}
419 \item \texttt{every <path> component}
420 \item \texttt{<path> component <number>}
421 \item \texttt{<path> component=<number>}
422 \end{enumerate}
423 \end{function}
424
425 \begin{function}{
426 insert gaps after components,
427 insert gaps globally after components,
428 insert gaps after segments,
429 insert gaps globally after segments
430 }
431 \begin{syntax}
432 |insert gaps after components=|\marg{path}\marg{gap}\marg{components}
433 |insert gaps after components=|\marg{path}\marg{gap}
434 |insert gaps globally after components=|\marg{path}\marg{gap}\marg{components}
435 |insert gaps globally after components=|\marg{path}\marg{gap}
436 |insert gaps after segments=|\marg{path}\marg{gap}\marg{segments}
437 |insert gaps after segments=|\marg{path}\marg{gap}
438 |insert gaps globally after segments=|\marg{path}\marg{gap}\marg{segments}
439 |insert gaps globally after segments=|\marg{path}\marg{gap}
440 \end{syntax}
441
442 This inserts a gap between components of a path by shortening the end of the specified component and start of the next one.
443 The list of components is passed through a |\foreach| loop so that syntax like |2,4,...,16| can be used.
444 If the list of components is not given the gaps are inserted between all components.
445
446 The \texttt{segments} versions work on the segments of the path rather than its components.
447 A \emph{segment} is a minimal drawing piece, meaning a line or B\'ezier curve.
448 \end{function}
449
450 \begin{function}{
451 join components,
452 join components globally
453 }
454 \begin{syntax}
455 |join components=|\marg{path}\marg{components}
456 |join components globally=|\marg{path}\marg{components}
457 \end{syntax}
458
459 This removes the |move| between each of the given components and the previous one.
460 The list of components is processed by |\foreach|.
461 If the component is the first one then it is joined to the last component.
462 \end{function}
463
464 \begin{function}{join components with, join components globally with, join components upright with, join components globally upright with, join components with curve, join components globally with curve}
465 \begin{syntax}
466 |join components with=|\marg{path}\marg{splice path}
467 |join components with=|\marg{path}\marg{splice path}\marg{list}
468 |join components upright with=|\marg{path}\marg{splice path}
469 |join components upright with=|\marg{path}\marg{splice path}\marg{list}
470 |join components with curve=|\marg{path}
471 |join components with curve=|\marg{path}\marg{list}
472 |join components globally with=|\marg{path}\marg{splice path}
473 |join components globally with=|\marg{path}\marg{splice path}\marg{list}
474 |join components globally upright with=|\marg{path}\marg{splice path}
475 |join components globally upright with=|\marg{path}\marg{splice path}\marg{list}
476 |join components globally with curve=|\marg{path}
477 |join components globally with curve=|\marg{path}\marg{list}
478 \end{syntax}
479
480 This inserts the |splice path| in the gaps between components of |path| specified by a comma separated list.
481 The splice is inserted between each specified component and the next one.
482 If the \marg{list} is not given (or is empty) then the splice is inserted between every component except that a \emph{spot weld} is performed first to join any components where the end of one is the start of the next.
483 The spot weld is only performed if the list of components is empty.
484
485 This does \emph{not} close the resulting path, even if the last component is specified in the list, for that see the key |close with|.
486
487 Note that because there is an optional third argument to this key, the second argument must always be enclosed in braces unless it is a single token.
488
489 The |upright| versions do a little test to see if the gap is oriented upside-down and if so then they insert the reflection of the splice path.
490
491 The |with curve| versions insert a single B\'ezier curve into the gap.
492 The curve is chosen to match the tangents of the segments either side of the gap and uses John Hobby's construction of a B\'ezier curve from its tangent directions.
493 \end{function}
494
495
496 \begin{function}{
497 spot weld,
498 spot weld globally
499 }
500 \begin{syntax}
501 |spot weld=|\meta{path}
502 |spot weld globally=|\meta{path}
503 \end{syntax}
504
505 This removes the \texttt{move} between any two components of the path where the end point of one component is the same as the initial point of the next (the tolerance on error here is \(0.01\)pt).
506 \end{function}
507
508 \begin{function}{
509 remove empty components,
510 remove empty components globally
511 }
512 \begin{syntax}
513 |remove empty components=|\meta{path}
514 |remove empty components globally=|\meta{path}
515 \end{syntax}
516
517 This removes empty components of the path (which consist of simply a move).
518 \end{function}
519
520 \begin{function}{
521 remove components,
522 remove components globally
523 }
524 \begin{syntax}
525 |remove components=|\marg{path}\marg{list}
526 |remove components globally=|\marg{path}\marg{list}
527 \end{syntax}
528
529 This removes the listed components of the path.
530 As with other list routines, the list is parsed via |foreach| first.
531 \end{function}
532
533 \begin{function}{open, open globally}
534 \begin{syntax}
535 |open=|\marg{path}
536 |open globally=|\marg{path}
537 \end{syntax}
538
539 These open the path by removing all of the closing elements.
540 If the closing elements add substantially to the path then they are replaced by a line segment.
541 \end{function}
542
543
544 \begin{function}{close, close globally, close with, close globally with, close with curve, close globally with curve, adjust and close, adjust and close globally}
545 \begin{syntax}
546 |close=|\marg{path}
547 |close globally=|\marg{path}
548 |close with=|\marg{path}\marg{splice path}
549 |close globally with=|\marg{path}\marg{splice path}
550 |close with curve=|\marg{path}
551 |close globally with curve=|\marg{path}
552 |adjust and close=|\marg{path}
553 |adjust and close globally=|\marg{path}
554 \end{syntax}
555
556 These all close the last component of the given path.
557 The first two will insert a line segment if the initial and final points of the component are not sufficiently close.
558 The two |with| variants allow you to specify another path to insert between the end and start of the path.
559 The two |with curve| variants insert a B\'ezier curve in the gap; the choice of curve depends on the tangents of the path segments being joined and uses John Hobby's B\'ezier curve construction (as used in the \texttt{hobby} TikZ library).
560 The two |adjust| variants shift the end point of the path so that it is at the same place as the start of that component.
561 If the last segment is a B\'ezier curve then the second control point is also shifted.
562 (The intention with the |adjust| keys is where the start and end of the component are very close together so the adjustment creates a smaller visual effect than adding in a line -- see Example~\ref{ex:close}.)
563 \end{function}
564
565 \begin{function}{splice, splice global}
566 \begin{syntax}
567 |splice=|\marg{initial path}\marg{splice path}\marg{final path}
568 |splice globally=|\marg{initial path}\marg{splice path}\marg{final path}
569 \end{syntax}
570
571 This splices the middle path into the gap between the initial and final paths.
572 The middle path is transformed to fit (don't try this with a path whose starting and ending points are close together) and the paths are joined so that the last component of the initial path and the first component of the splice path become a single component, and similarly at the other end.
573 \end{function}
574
575
576 \subsection{Shortening and Splitting Paths}
577
578 \begin{function}{
579 shorten at end,
580 shorten at start,
581 shorten at both ends,
582 shorten globally at end,
583 shorten globally at start,
584 shorten globally at both ends,
585 }
586 \begin{syntax}
587 |shorten at start=|\marg{path}\marg{length}
588 |shorten at end=|\marg{path}\marg{length}
589 |shorten at both ends=|\marg{path}\marg{length}
590 |shorten globally at start=|\marg{path}\marg{length}
591 |shorten globally at end=|\marg{path}\marg{length}
592 |shorten globally at both ends=|\marg{path}\marg{length}
593 \end{syntax}
594
595 This shortens a path by the given amount from the specified end.
596 The shortening is done so that it guarantees that it lies along the original path, but therefore the length is not completely guaranteed to be accurate.
597 This is particularly true for B\'ezier paths and if there is a very short segment at the end.
598
599 It uses the derivative at the end to work out how much to shorten by.
600 If wanting to shorten by a large amount it is better to shorten by a small amount a number of times.
601 \end{function}
602
603 \begin{function}{
604 split at,
605 split globally at,
606 split at into,
607 split globally at into,
608 split at keep start,
609 split globally at keep start,
610 split at keep end,
611 split globally at keep end,
612 split at keep middle,
613 split globally at keep middle,
614 }
615 \begin{syntax}
616 |split at=|\marg{path}\marg{parameter}
617 |split globally at=|\marg{path}\marg{parameter}
618 |split at into=|\marg{start path}\marg{end path}\marg{path}\marg{parameter}
619 |split globally at into=|\marg{start path}\marg{end path}\marg{path}\marg{parameter}
620 |split at keep start=|\marg{path}\marg{parameter}
621 |split globally at keep start=|\marg{path}\marg{parameter}
622 |split at keep end=|\marg{path}\marg{parameter}
623 |split globally at keep end=|\marg{path}\marg{parameter}
624 |split at keep middle=|\marg{path}\marg{parameter}\marg{parameter}
625 |split globally at keep middle=|\marg{path}\marg{parameter}\marg{parameter}
626 \end{syntax}
627
628 These keys split a path at a point specified by a parameter.
629 The interpretation of the parameter is described in Section~\ref{sec:coordinates}.
630
631 The first two keys replace the path with the split path, so this introduces a break at the point specified by the parameter.
632 The second two save the split path into a new path.
633
634 The ones with \texttt{keep} in the name split a path and keep the designated piece (so throw away the rest).
635 The ones that keep the middle need two parameters to specify the break points.
636
637 \end{function}
638
639 \begin{function}{
640 arrow shortening
641 }
642 \begin{syntax}
643 |arrow shortening|
644 |arrow shortening=|\marg{true{\OriginalBar}false}
645 \end{syntax}
646
647 When an arrow is added to a path then the path is shortened so that the arrow tip is at the end of where the path should end up.
648 Placing an arrow, therefore, has two effects: modifying the path and rendering the arrow.
649 The former should happen before a soft path is manipulated, the latter afterwards.
650 This key allows for the necessary separation to occur.
651 Invoking it when the path is used disables the shortening at that juncture.
652
653 Note that if the path (or its last segment) is very short then when the arrow is eventually placed it may end up pointing backwards.
654 Fixing this is on the \emph{ToDo} list!
655 \end{function}
656
657 \subsection{Exporting Paths}
658
659 There are two keys to export a path.
660
661 \begin{function}{save to aux}
662 \begin{syntax}
663 |save to aux=|\meta{path}
664 \end{syntax}
665
666 This will save the path to the auxfile so that it is available again on the next run through.
667 \end{function}
668
669 \begin{function}{export to svg}
670 \begin{syntax}
671 |export to svg=|\meta{path}
672 \end{syntax}
673
674 Saves the path to the file \texttt{path.svg} as an SVG document.
675 \end{function}
676
677 \subsection{Knots}
678
679 \begin{function}{
680 knot,
681 global knot,
682 draft mode
683 }
684 \begin{syntax}
685 |knot=|\marg{path}\marg{gap}\marg{components}
686 |global knot=|\marg{path}\marg{gap}\marg{components}
687 \end{syntax}
688
689 This style combines various of the above to make it simpler to draw knots and links.
690 It expands to:
691
692 \begin{lstlisting}
693 knot/.style n args={3}{
694 spath/.cd,
695 split at self intersections=#1,
696 insert gaps after components={#1}{#2}{#3},
697 maybe spot weld=#1,
698 render components=#1
699 }
700 \end{lstlisting}
701
702 (The \Verb+global+ version makes the path manipulating commands work globally.)
703
704 This splits a path at the points where it self-intersects and then inserts gaps between specified components.
705 The key |maybe spot weld| does a |spot weld| depending on whether or not the key |draft mode| is set to |true| or |false|.
706 The point here is that when designing the knot it is useful to not weld together components since that changes the component count.
707 But once the gaps are inserted in the desired places, welding the remaining components produces a nicer diagram.
708
709 The components can be styled using the keys as described in |render components|.
710 \end{function}
711
712 \subsection{Coordinates}
713 \label{sec:coordinates}
714
715 Soft paths are not natural TikZ objects and so when replaced back into a TikZ path construction then they don't fully interact with other TikZ things, like placing nodes at points on the path (though I've done my best to make that work).
716 To make things a little easier there is defined a coordinate system which identifies a point at a certain location along a soft path and keys which apply a transformation.
717
718 \begin{function}{spath cs}
719 \begin{syntax}
720 |(spath cs:|\marg{name} \marg{parameter}|)|
721 \end{syntax}
722
723 The location specification is a little technical.
724 It is specified as a number from \(0\) to \(1\), but the parameter works as follows.
725 Let \(n\) be the number of \emph{segments} on the path (these are the individual drawing elements that make up the path).
726 The interval from \(\frac{k-1}{n}\) to \(\frac{k}{n}\) is assigned to the \(k\)th segment of the path.
727 Then for a parameter in that interval, the location uses the natural parametrisation of that segment.
728 For a straight line, it is simply the proportional position along but for a B\'ezier curve then it uses the B\'ezier parametrisation.
729
730 The space is vital, so if the \texttt{name} is contained in a macro then a space has to be inserted somehow.
731 One option is to wrap the macro in braces, as seen in the examples in the next section.
732 \end{function}
733
734 \begin{function}{transform to, upright transform to}
735 \begin{syntax}
736 |transform to=|\marg{path}\marg{parameter}
737 |upright transform to=|\marg{path}\marg{parameter}
738 \end{syntax}
739
740 These keys (which are in the |spath| family) set the transformation so that the origin is at the specified point of the curve (as described above) and the \(x\)--axis is tangential to the curve.
741 The transformation is \emph{orthogonal} in that it is achieved by a rotation and a translation.
742
743 The first key aligns the axes so that the \(x\)--axis is in the forward direction of the path as that path was constructed.
744 The second key aligns the axes so that the \(y\)--axis points up the page.
745 The intention with the second key is that it is similar to what happens with the |sloped| key when a node is placed on a curve.
746 \end{function}
747
748 \section{Examples}
749
750 \begin{enumerate}
751 \item Saving and re-using.
752
753 \begin{example}
754 \begin{tikzpicture}
755 \path[spath/save=rpath] (0,0) to[out=30,in=150] (1,1);
756 \foreach \k in {1,...,9} {
757 \fill[green] (spath cs:rpath 0.\k) circle[radius=3pt];
758 \node[above left] at (spath cs:rpath 0.\k) {\(0.\k\)};
759 }
760 \fill[green] (2,2) circle[radius=3pt];
761 \draw[blue, spath/transform={rpath}{shift={(2,2)}}, spath/use=rpath] node[right] {transform};
762 \draw[orange] (3,0) [spath/use={rpath, move}] node[right] {moving};
763 \draw[red] (3,-1) -- +(0,2) [spath/append=rpath] node[above] {append};
764 \draw[spath/use=rpath] node[right] {use};
765 \end{tikzpicture}
766 \end{example}
767
768 \item Reversing.
769
770 \begin{example}
771 \begin{tikzpicture}
772 \path[spath/save=apath] (0,0) to[out=0,in=180] (2,1) to[out=0,in=180] (4,0);
773 \filldraw[
774 green,
775 draw=black,
776 ultra thick,
777 spath/use=apath
778 ] -- ++(0,-4) [spath/use={apath, reverse, move, weld}] -- cycle;
779 \end{tikzpicture}
780 \end{example}
781
782 \item Transformations.
783
784 \begin{example}
785 \begin{tikzpicture}
786 \draw[spath/save=tpath] (0,0) rectangle +(1,1);
787 \draw[rotate=45, xscale=2, yscale=3, ultra thick, red] (0,0) rectangle +(1,1);
788 \draw[
789 spath/transform={tpath}{rotate=45, xscale=2, yscale=3},
790 spath/use={tpath}];
791 \end{tikzpicture}
792 \end{example}
793
794 \begin{example}
795 \begin{tikzpicture}
796 \draw[spath/save=oval] (0,0) to[out=0,in=0] (0,2) to[out=180,in=180] (0,0);
797 \foreach \k in {0,...,9} {
798 \node[transform shape, spath/transform to={oval}{0.\k}] {k};
799 }
800 \begin{scope}[xshift = 3cm]
801 \draw[spath/save=soval] (0,0) to[out=0,in=0] (0,2) to[out=180,in=180] (0,0);
802 \foreach \k in {0,...,9} {
803 \node[transform shape, spath/upright transform to={soval}{0.\k}] {k};
804 }
805 \end{scope}
806 \end{tikzpicture}
807 \end{example}
808
809 \begin{example}
810 \begin{tikzpicture}
811 \path[draw=orange,ultra thick,spath/save=a] (3,2) -- ++(1,1) to[out=90,in=-90] ++(3,0);
812
813 \tikzset{
814 spath/span={a}{(4,5)}{(7,1)}
815 }
816
817 \fill
818 (4,5) circle[radius=3pt]
819 (7,1) circle[radius=3pt]
820 ;
821
822 \draw[spath/use=a];
823 \end{tikzpicture}
824 \end{example}
825
826
827 \item To paths.
828
829 \begin{example}
830 \begin{tikzpicture}
831 \path[draw=orange,ultra thick,spath/save=a] (3,2) -- ++(1,1) to[out=90,in=-90] ++(3,0);
832
833 \draw (0,0) -- +(1,1) to[spath/to={a}] node[pos=.6,auto] {node} ++(2,-1) -- +(3,1);
834 \end{tikzpicture}
835 \end{example}
836
837 \item Node placement.
838
839 \begin{example}
840 \begin{tikzpicture}
841 \path[spath/save=curve] (0,0) to[out=0,in=180] +(1,1);
842
843 \draw (0,0) -- (2,0) [spath/append=curve] node[pos=.5,auto,sloped] {node} -- +(2,0);
844
845 \end{tikzpicture}
846 \end{example}
847
848 \item Closing and adjusting paths.
849 \label{ex:close}
850
851 \begin{example}
852 \begin{tikzpicture}
853 \draw[line width=.2cm] (0,0) -- +(1,0) -- +(1,1) -- +(0,1) -- +(.01,.01);
854
855 \draw[line width=.2cm] (2,0) -- +(1,0) -- +(1,1) -- +(0,1) -- +(.01,.01)
856 -- cycle;
857
858 \draw[line width=.2cm] (4,0) -- +(1,0) -- +(1,1) -- +(0,1) -- +(.01,.01)
859 [spath/close=current];
860
861 \draw[line width=.2cm] (6,0) -- +(1,0) -- +(1,1) -- +(0,1) -- +(.01,.01)
862 [spath/adjust and close=current];
863 \end{tikzpicture}
864 \end{example}
865
866 \item Shortening.
867
868 \begin{example}
869 \begin{tikzpicture}
870 \path[spath/save=apath] (0,0) foreach \k in {1,...,4} { -- ++(1,0) +(0,0)};
871 \draw[
872 ultra thick,
873 red,
874 spath/.cd,
875 shorten at end={apath}{7pt},
876 shorten at start={apath}{9pt},
877 translate={apath}{0pt}{1pt},
878 use=apath,
879 ];
880 \draw (0,0) circle[radius=9pt] [spath/use=apath] circle[radius=7pt];
881 \end{tikzpicture}
882 \end{example}
883
884
885 \begin{example}
886 \begin{tikzpicture}
887 \path[spath/save=apath] (0,0) foreach \k in {1,...,4} { to[out=0,in=180] ++(1,0) +(0,0)};
888 \draw[
889 ultra thick,
890 red,
891 spath/.cd,
892 shorten at end={apath}{7pt},
893 shorten at start={apath}{9pt},
894 translate={apath}{0pt}{1pt},
895 use=apath,
896 ];
897 \draw (0,0) circle[radius=9pt] [spath/use=apath] circle[radius=7pt];
898 \end{tikzpicture}
899 \end{example}
900
901 \begin{example}
902 \begin{tikzpicture}
903 \draw[spath/save=npath] (0,0) foreach \k in {1,...,4} { -- ++(1,0) +(0,0)};
904 \draw[green] (0,0) -- +(0,-3pt) foreach \k in {1,...,4} { -- +(0,-3pt) ++(1,0)} -- +(0,-3pt);
905
906 \tikzset{
907 spath/.cd,
908 insert gaps after components={npath}{10pt}{1,3},
909 get components of={npath}\components,
910 }
911
912 \tikzset{
913 path 1/.style={
914 red,
915 },
916 }
917
918 \foreach[count=\k] \cpt in \components {
919 \path[
920 draw,
921 path \k/.try,
922 spath/.cd,
923 translate=\cpt{0pt}{\k pt},
924 use=\cpt,
925 ] +(0,3pt) -- +(0,-3pt);
926 \node[text=red] at (spath cs:{\cpt} .5) {\(\k\)};
927 }
928 \end{tikzpicture}
929 \end{example}
930
931 \begin{example}
932 \begin{tikzpicture}[>=Latex, line width=5pt]
933 % Just a simple line
934 \draw (0,1) to[bend left] +(5,0);
935 % Same line but with arrows, also save the path
936 \draw[->.>, spath/save=arrow] (0,0) to[bend left] +(5,0);
937 % Let's redraw that path without the arrows - it's short! But also distorted
938 \draw[spath/use={arrow,transform={yshift=-1cm}}];
939 % So if we redraw it with arrows it gets doubly shortened
940 \draw[->.>,spath/use={arrow,transform={yshift=-2cm}}];
941 % If we disable the shortening, the arrows end up in the right place
942 \draw[->.>,spath/use={arrow,transform={yshift=-3cm}}, spath/arrow shortening=false];
943 \end{tikzpicture}
944 \end{example}
945
946 \item Intersections.
947
948 One of the main motivations for implementing the intersection routines was to provide a different way of drawing knots and links and similar diagrams.
949
950 \begin{enumerate}
951
952 \item Define the two paths for the braid (usually these will be defined with |\path|).
953 \begin{example}
954 \begin{tikzpicture}[
955 use Hobby shortcut,
956 ]
957 \draw[spath/save global=pathA] (0,0) to[out=0,in=180] ++(2,1) to[out=0,in=180] ++(2,-1) to[out=0,in=180] ++(2,1) to[out=0,in=180] ++(2,-1);
958 \draw[spath/save global=pathB] (0,1) to[out=0,in=180] ++(2,-1) to[out=0,in=180] ++(2,1) to[out=0,in=180] ++(2,-1) to[out=0,in=180] ++(2,1);
959 \end{tikzpicture}
960 \end{example}
961
962 \item Split the paths at their mutual intersections and render them with a count of the components.
963
964 \begin{example}
965 \begin{tikzpicture}
966 \tikzset{
967 spath/.cd,
968 split at intersections={pathA}{pathB},
969 get components of={pathA}\pathAcomponents,
970 get components of={pathB}\pathBcomponents,
971 }
972
973 \foreach[count=\k] \cpt in \pathAcomponents {
974 \draw[spath/use=\cpt,-Circle];
975 \node[fill=white, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .5) {\(\k\)};
976 }
977
978 \foreach[count=\k] \cpt in \pathBcomponents {
979 \draw[spath/use=\cpt,-Circle];
980 \node[fill=white, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .5) {\(\k\)};
981 }
982 \end{tikzpicture}
983 \end{example}
984
985 \item Now we insert gaps after certain components in each path and then render the components.
986 To show that the gaps are genuine, we use a patterned background.
987 Although the paths were defined globally, the splitting in the previous example was local so we need to repeat it in this one.
988
989 \begin{example}
990 \begin{tikzpicture}
991 \tikzset{
992 spath/.cd,
993 split at intersections={pathA}{pathB},
994 insert gaps after components={pathA}{5pt}{1,3},
995 join components={pathA}{3,5},
996 get components of={pathA}\pathAcomponents,
997 insert gaps after components={pathB}{5pt}{2,4},
998 join components={pathB}{2,4},
999 get components of={pathB}\pathBcomponents,
1000 }
1001
1002 \fill[red!50!white] (-.5,-.5) rectangle (8.5,1.5);
1003 \fill[pattern=bricks, pattern color=white] (-.5,-.5) rectangle (8.5,1.5);
1004
1005 \foreach[count=\k] \cpt in \pathAcomponents {
1006 \draw[blue, line width=2pt,spath/use=\cpt];
1007 \node[fill=cyan, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .3) {\(\k\)};
1008 }
1009
1010 \foreach[count=\k] \cpt in \pathBcomponents {
1011 \draw[green, line width=2pt,spath/use=\cpt];
1012 \node[fill=green!50, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .3) {\(\k\)};
1013 }
1014 \end{tikzpicture}
1015 \end{example}
1016 \end{enumerate}
1017
1018 \item This example is notable because many of the intersection points are where segments of the path end, showing that the algorithm works well even in this circumstance.
1019
1020 \begin{enumerate}
1021 \item Here's the original path.
1022 \begin{example}
1023 \begin{tikzpicture}
1024 \draw[spath/save global=spiral] (5,0) -- (2.5,0) -- ++(0,-.25) -- ++(-2.5,0)
1025 arc[radius=2.25cm,start angle=180,end angle=90]
1026 arc[radius=2cm,start angle=90, delta angle=-180]
1027 arc[radius=1.75cm,start angle=-90, delta angle=-180]
1028 arc[radius=1.5cm,start angle=90, delta angle=-180]
1029 arc[radius=1.25cm,start angle=-90, delta angle=-180]
1030 arc[radius=1cm,start angle=90, delta angle=-180]
1031 arc[radius=.75cm,start angle=-90, delta angle=-180]
1032 arc[radius=.5cm,start angle=90, delta angle=-180]
1033 ;
1034 \end{tikzpicture}
1035 \end{example}
1036
1037 \item This renders labels on each component after splitting.
1038 \begin{example}
1039 \begin{tikzpicture}
1040 \tikzset{
1041 spath/.cd,
1042 split at self intersections=spiral,
1043 get components of={spiral}\pathcomponents,
1044 }
1045
1046 \foreach[count=\k] \cpt in \pathcomponents {
1047 \draw[spath/use=\cpt,-|];
1048 \node[fill=white, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .5) {\(\k\)};
1049 }
1050 \end{tikzpicture}
1051 \end{example}
1052
1053 \item Finally, we put the gaps in where we want them.
1054
1055 \begin{example}
1056 \begin{tikzpicture}
1057 \tikzset{
1058 spath/.cd,
1059 split at self intersections=spiral,
1060 insert gaps after components={spiral}{10pt}{1,3,5,7,10,11,14},
1061 spot weld=spiral,
1062 get components of={spiral}\pathcomponents,
1063 }
1064
1065 \foreach[count=\k] \cpt in \pathcomponents {
1066 \draw[blue, line width=2pt,spath/use=\cpt];
1067 }
1068 \end{tikzpicture}
1069 \end{example}
1070 \end{enumerate}
1071
1072 \item Here's a trefoil knot, demonstrating the \texttt{knot} style that simplifies creating knots.
1073 \begin{example}
1074 \begin{tikzpicture}[
1075 use Hobby shortcut,
1076 every trefoil component/.style={ultra thick, draw, red},
1077 trefoil component 1/.style={blue},
1078 ]
1079 \path[spath/save=trefoil] ([closed]90:2) foreach \k in {1,...,3} { .. (-30+\k*240:.5) .. (90+\k*240:2) } (90:2);
1080 \tikzset{spath/knot={trefoil}{8pt}{1,3,5}}
1081 \end{tikzpicture}
1082 \end{example}
1083
1084 \item Here's how to mark intersections of paths with ``bridges''.
1085 \begin{example}
1086 \begin{tikzpicture}
1087 \coordinate (a) at (-1,0.5);
1088 \coordinate (b) at (8,0.5);
1089 \coordinate (c) at (3,-0.5);
1090 \path[spath/save=sine]
1091 (-1.57,-1)
1092 cos ++(1.57,1)
1093 sin ++(1.57,1)
1094 cos ++(1.57,-1)
1095 sin ++(1.57,-1)
1096 cos ++(1.57,1)
1097 sin ++(1.57,1);
1098 \path[spath/save=over] (a) -- (c) |- (b);
1099
1100 \path[spath/save=arc] (0,0) arc[radius=1cm, start angle=180, delta angle=-180];
1101
1102 \tikzset{
1103 spath/split at intersections with={over}{sine},
1104 spath/insert gaps after components={over}{8pt},
1105 spath/join components upright with={over}{arc},
1106 spath/split at intersections with={sine}{over},
1107 spath/insert gaps after components={sine}{4pt},
1108 }
1109
1110 \draw[spath/use=sine];
1111 \draw[spath/use=over];
1112 \end{tikzpicture}
1113 \end{example}
1114
1115 \item If there are lots of paths like the previous example, here's a convenient style to put them together.
1116 \begin{example}
1117 \tikzset{
1118 bridging path/.initial=arc,
1119 bridging span/.initial=8pt,
1120 bridging gap/.initial=4pt,
1121 bridge/.style 2 args={
1122 spath/split at intersections with={#1}{#2},
1123 spath/insert gaps after components={#1}{\pgfkeysvalueof{/tikz/bridging span}},
1124 spath/join components upright with={#1}{\pgfkeysvalueof{/tikz/bridging path}},
1125 spath/split at intersections with={#2}{#1},
1126 spath/insert gaps after components={#2}{\pgfkeysvalueof{/tikz/bridging gap}},
1127 }
1128 }
1129
1130 % If used in the preamble, this needs surrounding in \AtBeginDocument
1131 %\AtBeginDocument{%
1132 \tikz[overlay] { \path[spath/save global=arc] (0,0) arc[radius=1cm, start angle=180, delta angle=-180]; }%
1133 %}
1134 \begin{tikzpicture}
1135 \path[spath/save=over] (0,0) -| ++(1,1) -| ++(-1,1) -| ++(1,1) -| ++(-1,1);
1136 \path[spath/save=under] (.5,-.5) -- ++(0,4);
1137 \tikzset{bridge={over}{under}}
1138 \draw[spath/use=over];
1139 \draw[spath/use=under];
1140 \end{tikzpicture}
1141 \end{example}
1142
1143 The command defining the arc does introduce a box which can introduce additional spacing.
1144 The syntax above, with the \% at the end of the lines, shouldn't add space but if for some reason it does then more sophisticated solutions to this are detailed at \href{https://tex.stackexchange.com/q/605800/86}{How to save or define a TikZ path for spath3 without introducing artifacts?}.
1145
1146 \end{enumerate}
1147 \end{document}