| 1 |
% Copyright 2018 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Constructing Paths} |
| 12 |
|
| 13 |
\subsection{Overview} |
| 14 |
|
| 15 |
The ``basic entity of drawing'' in \pgfname\ is the \emph{path}. A path |
| 16 |
consists of several parts, each of which is either a closed or open curve. An |
| 17 |
open curve has a starting point and an end point and, in between, consists of |
| 18 |
several \emph{segments}, each of which is either a straight line or a Bézier |
| 19 |
curve. Here is an example of a path (in red) consisting of two parts, one open, |
| 20 |
one closed: |
| 21 |
% |
| 22 |
\begin{codeexample}[] |
| 23 |
\begin{tikzpicture}[scale=2] |
| 24 |
\draw[thick,red] |
| 25 |
(0,0) coordinate (a) |
| 26 |
-- coordinate (ab) (1,.5) coordinate (b) |
| 27 |
.. coordinate (bc) controls +(up:1cm) and +(left:1cm) .. (3,1) coordinate (c) |
| 28 |
(0,1) -- (2,1) -- coordinate (x) (1,2) -- cycle; |
| 29 |
|
| 30 |
\draw (a) node[below] {start part 1} |
| 31 |
(ab) node[below right] {straight segment} |
| 32 |
(b) node[right] {end first segment} |
| 33 |
(c) node[right] {end part 1} |
| 34 |
(x) node[above right] {part 2 (closed)}; |
| 35 |
\end{tikzpicture} |
| 36 |
\end{codeexample} |
| 37 |
|
| 38 |
A path, by itself, has no ``effect'', that is, it does not leave any marks on |
| 39 |
the page. It is just a set of points on the plane. However, you can \emph{use} |
| 40 |
a path in different ways. The most natural actions are \emph{stroking} (also |
| 41 |
known as \emph{drawing}) and \emph{filling}. Stroking can be imagined as |
| 42 |
picking up a pen of a certain diameter and ``moving it along the path''. |
| 43 |
Filling means that everything ``inside'' the path is filled with a uniform |
| 44 |
color. Naturally, the open parts of a path must first be closed before a path |
| 45 |
can be filled. |
| 46 |
|
| 47 |
In \pgfname, there are numerous commands for constructing paths, all of which |
| 48 |
start with |\pgfpath|. There are also commands for \emph{using} paths, though |
| 49 |
most operations can be performed by calling |\pgfusepath| with an appropriate |
| 50 |
parameter. |
| 51 |
|
| 52 |
As a side-effect, the path construction commands keep track of two bounding |
| 53 |
boxes. One is the bounding box for the current path, the other is a bounding |
| 54 |
box for all paths in the current picture. See Section~\ref{section-bb} for more |
| 55 |
details. |
| 56 |
|
| 57 |
Each path construction command extends the current path in some way. The |
| 58 |
``current path'' is a global entity that persists across \TeX\ groups. Thus, |
| 59 |
between calls to the path construction commands you can perform arbitrary |
| 60 |
computations and even open and close \TeX\ groups. The current path only gets |
| 61 |
``flushed'' when the |\pgfusepath| command is called (or when the soft-path |
| 62 |
subsystem is used directly, see Section~\ref{section-soft-paths}). |
| 63 |
|
| 64 |
|
| 65 |
\subsection{The Move-To Path Operation} |
| 66 |
|
| 67 |
The most basic operation is the move-to operation. It must be given at the |
| 68 |
beginning of paths, though some path construction command (like |
| 69 |
|\pgfpathrectangle|) generate move-tos implicitly. A move-to operation can also |
| 70 |
be used to start a new part of a path. |
| 71 |
|
| 72 |
\begin{command}{\pgfpathmoveto\marg{coordinate}} |
| 73 |
This command expects a \pgfname-coordinate like |\pgfpointorigin| as its |
| 74 |
parameter. When the current path is empty, this operation will start the |
| 75 |
path at the given \meta{coordinate}. If a path has already been partly |
| 76 |
constructed, this command will end the current part of the path and start a |
| 77 |
new one. |
| 78 |
% |
| 79 |
\begin{codeexample}[] |
| 80 |
\begin{pgfpicture} |
| 81 |
\pgfpathmoveto{\pgfpointorigin} |
| 82 |
\pgfpathlineto{\pgfpoint{1cm}{1cm}} |
| 83 |
\pgfpathlineto{\pgfpoint{2cm}{1cm}} |
| 84 |
\pgfpathlineto{\pgfpoint{3cm}{0.5cm}} |
| 85 |
\pgfpathlineto{\pgfpoint{3cm}{0cm}} |
| 86 |
\pgfsetfillcolor{yellow!80!black} |
| 87 |
\pgfusepath{fill,stroke} |
| 88 |
\end{pgfpicture} |
| 89 |
\end{codeexample} |
| 90 |
% |
| 91 |
\begin{codeexample}[] |
| 92 |
\begin{pgfpicture} |
| 93 |
\pgfpathmoveto{\pgfpointorigin} |
| 94 |
\pgfpathlineto{\pgfpoint{1cm}{1cm}} |
| 95 |
\pgfpathlineto{\pgfpoint{2cm}{1cm}} |
| 96 |
\pgfpathmoveto{\pgfpoint{2cm}{1cm}} % New part |
| 97 |
\pgfpathlineto{\pgfpoint{3cm}{0.5cm}} |
| 98 |
\pgfpathlineto{\pgfpoint{3cm}{0cm}} |
| 99 |
\pgfsetfillcolor{yellow!80!black} |
| 100 |
\pgfusepath{fill,stroke} |
| 101 |
\end{pgfpicture} |
| 102 |
\end{codeexample} |
| 103 |
% |
| 104 |
The command will apply the current coordinate transformation matrix to |
| 105 |
\meta{coordinate} before using it. |
| 106 |
|
| 107 |
It will update the bounding box of the current path and picture, if |
| 108 |
necessary. |
| 109 |
\end{command} |
| 110 |
|
| 111 |
|
| 112 |
\subsection{The Line-To Path Operation} |
| 113 |
|
| 114 |
\begin{command}{\pgfpathlineto\marg{coordinate}} |
| 115 |
This command extends the current path in a straight line to the given |
| 116 |
\meta{coordinate}. If this command is given at the beginning of path |
| 117 |
without any other path construction command given before (in particular |
| 118 |
without a move-to operation), the \TeX\ file may compile without an error |
| 119 |
message, but a viewer application may display an error message when trying |
| 120 |
to render the picture. |
| 121 |
% |
| 122 |
\begin{codeexample}[] |
| 123 |
\begin{pgfpicture} |
| 124 |
\pgfpathmoveto{\pgfpointorigin} |
| 125 |
\pgfpathlineto{\pgfpoint{1cm}{1cm}} |
| 126 |
\pgfpathlineto{\pgfpoint{2cm}{1cm}} |
| 127 |
\pgfsetfillcolor{yellow!80!black} |
| 128 |
\pgfusepath{fill,stroke} |
| 129 |
\end{pgfpicture} |
| 130 |
\end{codeexample} |
| 131 |
% |
| 132 |
The command will apply the current coordinate transformation matrix to |
| 133 |
\meta{coordinate} before using it. |
| 134 |
|
| 135 |
It will update the bounding box of the current path and picture, if |
| 136 |
necessary. |
| 137 |
\end{command} |
| 138 |
|
| 139 |
|
| 140 |
\subsection{The Curve-To Path Operations} |
| 141 |
|
| 142 |
\begin{command}{\pgfpathcurveto\marg{support 1}\marg{support 2}\marg{coordinate}} |
| 143 |
This command extends the current path with a Bézier curve from the last |
| 144 |
point of the path to \meta{coordinate}. The \meta{support 1} and |
| 145 |
\meta{support 2} are the first and second support point of the Bézier |
| 146 |
curve. For more information on Bézier curves, please consult a standard |
| 147 |
textbook on computer graphics. |
| 148 |
|
| 149 |
Like the line-to command, this command may not be the first path |
| 150 |
construction command in a path. |
| 151 |
\begin{codeexample}[] |
| 152 |
\begin{pgfpicture} |
| 153 |
\pgfpathmoveto{\pgfpointorigin} |
| 154 |
\pgfpathcurveto |
| 155 |
{\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{1cm}}{\pgfpoint{3cm}{0cm}} |
| 156 |
\pgfsetfillcolor{yellow!80!black} |
| 157 |
\pgfusepath{fill,stroke} |
| 158 |
\end{pgfpicture} |
| 159 |
\end{codeexample} |
| 160 |
% |
| 161 |
The command will apply the current coordinate transformation matrix to |
| 162 |
\meta{coordinate} before using it. |
| 163 |
|
| 164 |
It will update the bounding box of the current path and picture, if |
| 165 |
necessary. However, the bounding box is simply made large enough such that |
| 166 |
it encompasses all of the support points and the \meta{coordinate}. This |
| 167 |
will guarantee that the curve is completely inside the bounding box, but |
| 168 |
the bounding box will typically be quite a bit too large. It is not clear |
| 169 |
(to me) how this can be avoided without resorting to ``some serious math'' |
| 170 |
in order to calculate a precise bounding box. |
| 171 |
\end{command} |
| 172 |
|
| 173 |
\begin{command}{\pgfpathquadraticcurveto\marg{support}\marg{coordinate}} |
| 174 |
This command works like |\pgfpathcurveto|, only it uses a quadratic Bézier |
| 175 |
curve rather than a cubic one. This means that only one support point is |
| 176 |
needed. |
| 177 |
% |
| 178 |
\begin{codeexample}[] |
| 179 |
\begin{pgfpicture} |
| 180 |
\pgfpathmoveto{\pgfpointorigin} |
| 181 |
\pgfpathquadraticcurveto |
| 182 |
{\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{0cm}} |
| 183 |
\pgfsetfillcolor{yellow!80!black} |
| 184 |
\pgfusepath{fill,stroke} |
| 185 |
\end{pgfpicture} |
| 186 |
\end{codeexample} |
| 187 |
% |
| 188 |
Internally, the quadratic curve is converted into a cubic curve. The only |
| 189 |
noticeable effect of this is that the points used for computing the |
| 190 |
bounding box are the control points of the converted curve rather than |
| 191 |
\meta{support}. The main effect of this is that the bounding box will be a |
| 192 |
bit tighter than might be expected. In particular, \meta{support} will not |
| 193 |
always be part of the bounding box. |
| 194 |
\end{command} |
| 195 |
|
| 196 |
There exist two commands to draw only part of a cubic Bézier curve: |
| 197 |
|
| 198 |
\begin{command}{\pgfpathcurvebetweentime\marg{time $t_1$}\marg{time $t_2$}\marg{point p}\marg{point $s_1$}\marg{point $s_2$}\marg{point q}} |
| 199 |
This command draws the part of the curve described by $p$, $s_1$, $s_2$ and |
| 200 |
$q$ between the times $t_1$ and $t_2$. A time value of 0 indicates the |
| 201 |
point $p$ and a time value of 1 indicates point $q$. This command includes |
| 202 |
a moveto operation to the first point. |
| 203 |
% |
| 204 |
\begin{codeexample}[] |
| 205 |
\begin{tikzpicture} |
| 206 |
\draw [thin] (0,0) .. controls (0,2) and (3,0) .. (3,2); |
| 207 |
\pgfpathcurvebetweentime{0.25}{0.9}{\pgfpointxy{0}{0}}{\pgfpointxy{0}{2}} |
| 208 |
{\pgfpointxy{3}{0}}{\pgfpointxy{3}{2}} |
| 209 |
\pgfsetstrokecolor{red} |
| 210 |
\pgfsetstrokeopacity{0.5} |
| 211 |
\pgfsetlinewidth{2pt} |
| 212 |
\pgfusepath{stroke} |
| 213 |
\end{tikzpicture} |
| 214 |
\end{codeexample} |
| 215 |
% |
| 216 |
\end{command} |
| 217 |
|
| 218 |
\begin{command}{\pgfpathcurvebetweentimecontinue\marg{time $t_1$}\marg{time $t_2$}\marg{point p}\marg{point $s_1$}\marg{point $s_2$}\marg{point q}} |
| 219 |
This command works like |\pgfpathcurvebetweentime|, except that a moveto |
| 220 |
operation is \emph{not} made to the first point. |
| 221 |
\end{command} |
| 222 |
|
| 223 |
|
| 224 |
\subsection{The Close Path Operation} |
| 225 |
|
| 226 |
\begin{command}{\pgfpathclose} |
| 227 |
This command closes the current part of the path by appending a straight |
| 228 |
line to the start point of the current part. Note that there \emph{is} a |
| 229 |
difference between closing a path and using the line-to operation to add a |
| 230 |
straight line to the start of the current path. The difference is |
| 231 |
demonstrated by the upper corners of the triangles in the following |
| 232 |
example: |
| 233 |
% |
| 234 |
\begin{codeexample}[] |
| 235 |
\begin{tikzpicture} |
| 236 |
\draw[help lines] (0,0) grid (3,2); |
| 237 |
\pgfsetlinewidth{5pt} |
| 238 |
\pgfpathmoveto{\pgfpoint{1cm}{1cm}} |
| 239 |
\pgfpathlineto{\pgfpoint{0cm}{-1cm}} |
| 240 |
\pgfpathlineto{\pgfpoint{1cm}{-1cm}} |
| 241 |
\pgfpathclose |
| 242 |
\pgfpathmoveto{\pgfpoint{2.5cm}{1cm}} |
| 243 |
\pgfpathlineto{\pgfpoint{1.5cm}{-1cm}} |
| 244 |
\pgfpathlineto{\pgfpoint{2.5cm}{-1cm}} |
| 245 |
\pgfpathlineto{\pgfpoint{2.5cm}{1cm}} |
| 246 |
\pgfusepath{stroke} |
| 247 |
\end{tikzpicture} |
| 248 |
\end{codeexample} |
| 249 |
% |
| 250 |
\end{command} |
| 251 |
|
| 252 |
|
| 253 |
\subsection{Arc, Ellipse and Circle Path Operations} |
| 254 |
|
| 255 |
The path construction commands that we have discussed up to now are sufficient |
| 256 |
to create all paths that can be created ``at all''. However, it is useful to |
| 257 |
have special commands to create certain shapes, like circles, that arise often |
| 258 |
in practice. |
| 259 |
|
| 260 |
In the following, the commands for adding (parts of) (transformed) circles to a |
| 261 |
path are described. |
| 262 |
|
| 263 |
\begin{command}{\pgfpatharc\marg{start angle}\marg{end angle}{\ttfamily\char`\{}\meta{radius}\opt{| and |\meta{y-radius}}{\ttfamily\char`\}}} |
| 264 |
This command appends a part of a circle (or an ellipse) to the current |
| 265 |
path. Imagine the curve between \meta{start angle} and \meta{end angle} on |
| 266 |
a circle of radius \meta{radius} (if $\meta{start angle} < \meta{end |
| 267 |
angle}$, the curve goes around the circle counterclockwise, otherwise |
| 268 |
clockwise). This curve is now moved such that the point where the curve |
| 269 |
starts is the previous last point of the path. Note that this command will |
| 270 |
\emph{not} start a new part of the path, which is important for example for |
| 271 |
filling purposes. |
| 272 |
% |
| 273 |
\begin{codeexample}[] |
| 274 |
\begin{tikzpicture} |
| 275 |
\draw[help lines] (0,0) grid (3,2); |
| 276 |
\pgfpathmoveto{\pgfpointorigin} |
| 277 |
\pgfpathlineto{\pgfpoint{0cm}{1cm}} |
| 278 |
\pgfpatharc{180}{90}{.5cm} |
| 279 |
\pgfpathlineto{\pgfpoint{3cm}{1.5cm}} |
| 280 |
\pgfpatharc{90}{-45}{.5cm} |
| 281 |
\pgfusepath{fill} |
| 282 |
\end{tikzpicture} |
| 283 |
\end{codeexample} |
| 284 |
|
| 285 |
Saying |\pgfpatharc{0}{360}{1cm}| ``nearly'' gives you a full circle. The |
| 286 |
``nearly'' refers to the fact that the circle will not be closed. You can |
| 287 |
close it using |\pgfpathclose|. |
| 288 |
|
| 289 |
If the optional \meta{y-radius} is given, the \meta{radius} is the |
| 290 |
$x$-radius and the \meta{y-radius} the $y$-radius of the ellipse from which |
| 291 |
the curve is taken: |
| 292 |
% |
| 293 |
\begin{codeexample}[] |
| 294 |
\begin{tikzpicture} |
| 295 |
\draw[help lines] (0,0) grid (3,2); |
| 296 |
\pgfpathmoveto{\pgfpointorigin} |
| 297 |
\pgfpatharc{180}{45}{2cm and 1cm} |
| 298 |
\pgfusepath{draw} |
| 299 |
\end{tikzpicture} |
| 300 |
\end{codeexample} |
| 301 |
|
| 302 |
The axes of the circle or ellipse from which the arc is ``taken'' always |
| 303 |
point up and right. However, the current coordinate transformation matrix |
| 304 |
will have an effect on the arc. This can be used to, say, rotate an arc: |
| 305 |
% |
| 306 |
\begin{codeexample}[] |
| 307 |
\begin{tikzpicture} |
| 308 |
\draw[help lines] (0,0) grid (3,2); |
| 309 |
\pgftransformrotate{30} |
| 310 |
\pgfpathmoveto{\pgfpointorigin} |
| 311 |
\pgfpatharc{180}{45}{2cm and 1cm} |
| 312 |
\pgfusepath{draw} |
| 313 |
\end{tikzpicture} |
| 314 |
\end{codeexample} |
| 315 |
|
| 316 |
The command will update the bounding box of the current path and picture, |
| 317 |
if necessary. Unless rotation or shearing transformations are applied, the |
| 318 |
bounding box will be tight. |
| 319 |
\end{command} |
| 320 |
|
| 321 |
\begin{command}{\pgfpatharcaxes\marg{start angle}\marg{end angle}\marg{first axis}\marg{second axis}} |
| 322 |
This command is similar to |\pgfpatharc|. The main difference is how the |
| 323 |
ellipse or circle is specified from which the arc is taken. The two |
| 324 |
parameters \meta{first axis} and \meta{second axis} are the $0^\circ$-axis |
| 325 |
and the $90^\circ$-axis of the ellipse from which the path is taken. Thus, |
| 326 |
|\pgfpatharc{0}{90}{1cm and 2cm}| has the same effect as |
| 327 |
% |
| 328 |
\begin{verbatim} |
| 329 |
\pgfpatharcaxes{0}{90}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{2cm}} |
| 330 |
\end{verbatim} |
| 331 |
% |
| 332 |
\begin{codeexample}[] |
| 333 |
\begin{tikzpicture} |
| 334 |
\draw[help lines] (0,0) grid (3,2); |
| 335 |
\draw (0,0) -- (2cm,5mm) (0,0) -- (0cm,1cm); |
| 336 |
|
| 337 |
\pgfpathmoveto{\pgfpoint{2cm}{5mm}} |
| 338 |
\pgfpatharcaxes{0}{90}{\pgfpoint{2cm}{5mm}}{\pgfpoint{0cm}{1cm}} |
| 339 |
\pgfusepath{draw} |
| 340 |
\end{tikzpicture} |
| 341 |
\end{codeexample} |
| 342 |
% |
| 343 |
\end{command} |
| 344 |
|
| 345 |
\begin{command}{\pgfpatharcto\marg{x-radius}\marg{y-radius}\marg{rotation} \marg{large arc flag}\marg{counterclockwise flag}\\\marg{target point}} |
| 346 |
This command (which directly corresponds to the arc-path command of |
| 347 |
\textsc{svg}) is used to add an arc to the path that starts at the current |
| 348 |
point and ends at \meta{target point}. This arc is part of an ellipse that |
| 349 |
is determined in the following way: Imagine an ellipse with radii |
| 350 |
\meta{x-radius} and \meta{y-radius} that is rotated around its center by |
| 351 |
\meta{rotation} degrees. When you move this ellipse around in the plane, |
| 352 |
there will be exactly two positions such that the two current point and the |
| 353 |
target point lie on the border of the ellipse (excluding pathological |
| 354 |
cases). The flags \meta{large arc flag} and \meta{clockwise flag} are then |
| 355 |
used to decide which of these ellipses should be picked and which arc on |
| 356 |
the picked ellipsis should be used. |
| 357 |
% |
| 358 |
\begin{codeexample}[] |
| 359 |
\begin{tikzpicture} |
| 360 |
\draw[help lines] (0,0) grid (3,2); |
| 361 |
|
| 362 |
\pgfpathmoveto{\pgfpoint{0mm}{20mm}} |
| 363 |
\pgfpatharcto{3cm}{1cm}{0}{0}{0}{\pgfpoint{3cm}{1cm}} |
| 364 |
\pgfusepath{draw} |
| 365 |
\end{tikzpicture} |
| 366 |
\end{codeexample} |
| 367 |
% |
| 368 |
Both flags are considered to be false exactly if they evaluate to |0|, |
| 369 |
otherwise they are true. If the \meta{large arc flag} is true, then the |
| 370 |
angle spanned by the arc will be greater than $180^\circ$, otherwise it |
| 371 |
will be less than $180^\circ$. The \meta{clockwise flag} is used to |
| 372 |
determine which of the two ellipses should be used: if the flag is true, |
| 373 |
then the arc goes from the current point to the target point in a |
| 374 |
counterclockwise direction, otherwise in a clockwise fashion. |
| 375 |
% |
| 376 |
\begin{codeexample}[] |
| 377 |
\begin{tikzpicture} |
| 378 |
\pgfsetlinewidth{2pt} |
| 379 |
% Flags 0 0: red |
| 380 |
\pgfsetstrokecolor{red} |
| 381 |
\pgfpathmoveto{\pgfpointorigin} |
| 382 |
\pgfpatharcto{20pt}{10pt}{0}{0}{0}{\pgfpoint{20pt}{10pt}} |
| 383 |
\pgfusepath{stroke} |
| 384 |
% Flags 0 1: blue |
| 385 |
\pgfsetstrokecolor{blue} |
| 386 |
\pgfpathmoveto{\pgfpointorigin} |
| 387 |
\pgfpatharcto{20pt}{10pt}{0}{0}{1}{\pgfpoint{20pt}{10pt}} |
| 388 |
\pgfusepath{stroke} |
| 389 |
% Flags 1 0: orange |
| 390 |
\pgfsetstrokecolor{orange} |
| 391 |
\pgfpathmoveto{\pgfpointorigin} |
| 392 |
\pgfpatharcto{20pt}{10pt}{0}{1}{0}{\pgfpoint{20pt}{10pt}} |
| 393 |
\pgfusepath{stroke} |
| 394 |
% Flags 1 1: black |
| 395 |
\pgfsetstrokecolor{black} |
| 396 |
\pgfpathmoveto{\pgfpointorigin} |
| 397 |
\pgfpatharcto{20pt}{10pt}{0}{1}{1}{\pgfpoint{20pt}{10pt}} |
| 398 |
\pgfusepath{stroke} |
| 399 |
\end{tikzpicture} |
| 400 |
\end{codeexample} |
| 401 |
% |
| 402 |
\emph{Warning:} The internal computations necessary for this command are |
| 403 |
numerically very unstable. In particular, the arc will not always really |
| 404 |
end at the \meta{target coordinate}, but may be off by up to several |
| 405 |
points. A more precise positioning is currently infeasible due to \TeX's |
| 406 |
numerical weaknesses. The only case it works quite nicely is when the |
| 407 |
resulting angle is a multiple of~$90^\circ$. |
| 408 |
\end{command} |
| 409 |
|
| 410 |
\begin{command}{\pgfpatharctoprecomputed\marg{center point}\marg{start angle}\marg{end angle}\marg{end point}\\\marg{x-radius}\marg{y-radius}\marg{ratio x-radius/y-radius}\marg{ratio y-radius/x-radius}} |
| 411 |
A specialized arc operation which is fast and numerically stable, provided |
| 412 |
a lot of information is given in advance. |
| 413 |
|
| 414 |
In contrast to |\pgfpatharc|, it explicitly interpolates start and end |
| 415 |
points. |
| 416 |
|
| 417 |
In contrast to |\pgfpatharcto|, this routine is numerically stable and |
| 418 |
quite fast since it relies on a lot of available information. |
| 419 |
% |
| 420 |
\begin{codeexample}[] |
| 421 |
\begin{tikzpicture} |
| 422 |
\draw[help lines] (0,0) grid (3,2); |
| 423 |
|
| 424 |
\def\cx{1.5cm}% center x |
| 425 |
\def\cy{1cm}% center y |
| 426 |
\def\startangle{0}% |
| 427 |
\def\endangle{270}% |
| 428 |
\def\a{1.5cm}% xradius |
| 429 |
\def\b{0.5cm}% yradius |
| 430 |
\pgfmathparse{\a/\b}\let\abratio=\pgfmathresult |
| 431 |
\pgfmathparse{\b/\a}\let\baratio=\pgfmathresult |
| 432 |
% |
| 433 |
% start point: |
| 434 |
\pgfpathmoveto{\pgfpoint{\cx+\a*cos(\startangle)}{\cy+\b*sin(\startangle)}}% |
| 435 |
\pgfpatharctoprecomputed |
| 436 |
{\pgfpoint{\cx}{\cy}} |
| 437 |
{\startangle} |
| 438 |
{\endangle} |
| 439 |
{\pgfpoint{\cx+\a*cos(\endangle)}{\cy+\b*sin(\endangle)}}% end point |
| 440 |
{\a} |
| 441 |
{\b} |
| 442 |
{\abratio} |
| 443 |
{\baratio} |
| 444 |
\pgfusepath{draw} |
| 445 |
\end{tikzpicture} |
| 446 |
\end{codeexample} |
| 447 |
|
| 448 |
\begin{command}{\pgfpatharctomaxstepsize} |
| 449 |
The quality of arc approximation taken by |\pgfpatharctoprecomputed| by |
| 450 |
means of Bézier splines is controlled by a mesh width, which is |
| 451 |
initially |
| 452 |
|
| 453 |
|\def\pgfpatharctoprecomputed{45}|. |
| 454 |
|
| 455 |
The mesh width is provided in (full!) degrees. The smaller the mesh |
| 456 |
width, the more precise the arc approximation. |
| 457 |
|
| 458 |
Use an empty value to disable spline approximation (uses a single cubic |
| 459 |
polynomial for the complete arc). |
| 460 |
|
| 461 |
The value must be an integer! |
| 462 |
\end{command} |
| 463 |
\end{command} |
| 464 |
|
| 465 |
\begin{command}{\pgfpathellipse\marg{center}\marg{first axis}\marg{second axis}} |
| 466 |
The effect of this command is to append an ellipse to the current path (if |
| 467 |
the path is not empty, a new part is started). The ellipse's center will be |
| 468 |
\meta{center} and \meta{first axis} and \meta{second axis} are the axis |
| 469 |
\emph{vectors}. The same effect as this command can also be achieved using |
| 470 |
an appropriate sequence of move-to, arc, and close operations, but this |
| 471 |
command is easier and faster. |
| 472 |
% |
| 473 |
\begin{codeexample}[] |
| 474 |
\begin{tikzpicture} |
| 475 |
\draw[help lines] (0,0) grid (3,2); |
| 476 |
\pgfpathellipse{\pgfpoint{1cm}{0cm}} |
| 477 |
{\pgfpoint{1.5cm}{0cm}} |
| 478 |
{\pgfpoint{0cm}{1cm}} |
| 479 |
\pgfusepath{draw} |
| 480 |
\color{red} |
| 481 |
\pgfpathellipse{\pgfpoint{1cm}{0cm}} |
| 482 |
{\pgfpoint{1cm}{1cm}} |
| 483 |
{\pgfpoint{-0.5cm}{0.5cm}} |
| 484 |
\pgfusepath{draw} |
| 485 |
\end{tikzpicture} |
| 486 |
\end{codeexample} |
| 487 |
|
| 488 |
The command will apply coordinate transformations to all coordinates of the |
| 489 |
ellipse. However, the coordinate transformations are applied only after the |
| 490 |
ellipse is ``finished conceptually''. Thus, a transformation of 1cm to the |
| 491 |
right will simply shift the ellipse one centimeter to the right; it will |
| 492 |
not add 1cm to the $x$-coordinates of the two axis vectors. |
| 493 |
|
| 494 |
The command will update the bounding box of the current path and picture, |
| 495 |
if necessary. |
| 496 |
\end{command} |
| 497 |
|
| 498 |
\begin{command}{\pgfpathcircle\marg{center}\marg{radius}} |
| 499 |
A shorthand for |\pgfpathellipse| applied to \meta{center} and the two axis |
| 500 |
vectors $(\meta{radius},0)$ and $(0,\meta{radius})$. |
| 501 |
\end{command} |
| 502 |
|
| 503 |
|
| 504 |
\subsection{Rectangle Path Operations} |
| 505 |
|
| 506 |
Another shape that arises frequently is the rectangle. Two commands can be used |
| 507 |
to add a rectangle to the current path. Both commands will start a new part of |
| 508 |
the path. |
| 509 |
|
| 510 |
\begin{command}{\pgfpathrectangle\marg{corner}\marg{diagonal vector}} |
| 511 |
Adds a rectangle to the path whose one corner is \meta{corner} and whose |
| 512 |
opposite corner is given by $\meta{corner} + \meta{diagonal vector}$. |
| 513 |
% |
| 514 |
\begin{codeexample}[] |
| 515 |
\begin{tikzpicture} |
| 516 |
\draw[help lines] (0,0) grid (3,2); |
| 517 |
\pgfpathrectangle{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}} |
| 518 |
\pgfpathrectangle{\pgfpoint{1.5cm}{0.25cm}}{\pgfpoint{1.5cm}{1cm}} |
| 519 |
\pgfpathrectangle{\pgfpoint{2cm}{0.5cm}}{\pgfpoint{1.5cm}{1cm}} |
| 520 |
\pgfusepath{draw} |
| 521 |
\end{tikzpicture} |
| 522 |
\end{codeexample} |
| 523 |
% |
| 524 |
The command will apply coordinate transformations and update the bounding |
| 525 |
boxes tightly. |
| 526 |
\end{command} |
| 527 |
|
| 528 |
\begin{command}{\pgfpathrectanglecorners\marg{corner}\marg{opposite corner}} |
| 529 |
Adds a rectangle to the path whose two opposing corners are \meta{corner} |
| 530 |
and \meta{opposite corner}. |
| 531 |
% |
| 532 |
\begin{codeexample}[] |
| 533 |
\begin{tikzpicture} |
| 534 |
\draw[help lines] (0,0) grid (3,2); |
| 535 |
\pgfpathrectanglecorners{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}} |
| 536 |
\pgfusepath{draw} |
| 537 |
\end{tikzpicture} |
| 538 |
\end{codeexample} |
| 539 |
% |
| 540 |
The command will apply coordinate transformations and update the bounding |
| 541 |
boxes tightly. |
| 542 |
\end{command} |
| 543 |
|
| 544 |
|
| 545 |
\subsection{The Grid Path Operation} |
| 546 |
|
| 547 |
\begin{command}{\pgfpathgrid\oarg{options}\marg{first corner}\marg{second corner}} |
| 548 |
Appends a grid to the current path. That is, a (possibly large) number of |
| 549 |
parts are added to the path, each part consisting of a single horizontal or |
| 550 |
vertical straight line segment. |
| 551 |
|
| 552 |
Conceptually, the origin is part of the grid and the grid is clipped to the |
| 553 |
rectangle specified by the \meta{first corner} and the \meta{second |
| 554 |
corner}. However, no clipping occurs (this command just adds parts to the |
| 555 |
current path) and the points where the lines enter and leave the ``clipping |
| 556 |
area'' are computed and used to add simple lines to the current path. |
| 557 |
|
| 558 |
The following keys influence the grid: |
| 559 |
% |
| 560 |
\begin{key}{/pgf/stepx=\meta{dimension} (initially 1cm)} |
| 561 |
The horizontal stepping. |
| 562 |
\end{key} |
| 563 |
% |
| 564 |
\begin{key}{/pgf/stepy=\meta{dimension} (initially 1cm)} |
| 565 |
The vertical stepping. |
| 566 |
\end{key} |
| 567 |
% |
| 568 |
\begin{key}{/pgf/step=\meta{vector}} |
| 569 |
Sets the horizontal stepping to the $x$-coordinate of \meta{vector} and |
| 570 |
the vertical stepping to its $y$-coordinate. |
| 571 |
\end{key} |
| 572 |
% |
| 573 |
\begin{codeexample}[] |
| 574 |
\begin{pgfpicture} |
| 575 |
\pgfsetlinewidth{0.8pt} |
| 576 |
\pgfpathgrid[step={\pgfpoint{1cm}{1cm}}] |
| 577 |
{\pgfpoint{-3mm}{-3mm}}{\pgfpoint{33mm}{23mm}} |
| 578 |
\pgfusepath{stroke} |
| 579 |
\pgfsetlinewidth{0.4pt} |
| 580 |
\pgfpathgrid[stepx=1mm,stepy=1mm] |
| 581 |
{\pgfpoint{-1.5mm}{-1.5mm}}{\pgfpoint{31.5mm}{21.5mm}} |
| 582 |
\pgfusepath{stroke} |
| 583 |
\end{pgfpicture} |
| 584 |
\end{codeexample} |
| 585 |
% |
| 586 |
The command will apply coordinate transformations and update the bounding |
| 587 |
boxes. As for ellipses, the transformations are applied to the |
| 588 |
``conceptually finished'' grid. |
| 589 |
% |
| 590 |
\begin{codeexample}[] |
| 591 |
\begin{pgfpicture} |
| 592 |
\pgftransformrotate{10} |
| 593 |
\pgfpathgrid[stepx=1mm,stepy=2mm]{\pgfpoint{0mm}{0mm}}{\pgfpoint{30mm}{30mm}} |
| 594 |
\pgfusepath{stroke} |
| 595 |
\end{pgfpicture} |
| 596 |
\end{codeexample} |
| 597 |
% |
| 598 |
\end{command} |
| 599 |
|
| 600 |
|
| 601 |
\subsection{The Parabola Path Operation} |
| 602 |
|
| 603 |
\begin{command}{\pgfpathparabola\marg{bend vector}\marg{end vector}} |
| 604 |
This command appends two half-parabolas to the current path. The first |
| 605 |
starts at the current point and ends at the current point plus \meta{bend |
| 606 |
vector}. At this point, it has its bend. The second half parabola starts at |
| 607 |
that bend point and ends at point that is given by the bend plus \meta{end |
| 608 |
vector}. |
| 609 |
|
| 610 |
If you set \meta{end vector} to the null vector, you append only a half |
| 611 |
parabola that goes from the current point to the bend; by setting |
| 612 |
\meta{bend vector} to the null vector, you append only a half parabola that |
| 613 |
goes through the current point and \meta{end vector} and has its bend at |
| 614 |
the current point. |
| 615 |
|
| 616 |
It is not possible to use this command to draw a part of a parabola that |
| 617 |
does not contain the bend. |
| 618 |
% |
| 619 |
\begin{codeexample}[] |
| 620 |
\begin{pgfpicture} |
| 621 |
% Half-parabola going ``up and right'' |
| 622 |
\pgfpathmoveto{\pgfpointorigin} |
| 623 |
\pgfpathparabola{\pgfpointorigin}{\pgfpoint{2cm}{4cm}} |
| 624 |
\color{red} |
| 625 |
\pgfusepath{stroke} |
| 626 |
|
| 627 |
% Half-parabola going ``down and right'' |
| 628 |
\pgfpathmoveto{\pgfpointorigin} |
| 629 |
\pgfpathparabola{\pgfpoint{-2cm}{4cm}}{\pgfpointorigin} |
| 630 |
\color{blue} |
| 631 |
\pgfusepath{stroke} |
| 632 |
|
| 633 |
% Full parabola |
| 634 |
\pgfpathmoveto{\pgfpoint{-2cm}{2cm}} |
| 635 |
\pgfpathparabola{\pgfpoint{1cm}{-1cm}}{\pgfpoint{2cm}{4cm}} |
| 636 |
\color{orange} |
| 637 |
\pgfusepath{stroke} |
| 638 |
\end{pgfpicture} |
| 639 |
\end{codeexample} |
| 640 |
% |
| 641 |
The command will apply coordinate transformations and update the bounding |
| 642 |
boxes. |
| 643 |
\end{command} |
| 644 |
|
| 645 |
|
| 646 |
\subsection{Sine and Cosine Path Operations} |
| 647 |
|
| 648 |
Sine and cosine curves often need to be drawn and the following commands may |
| 649 |
help with this. However, they only allow you to append sine and cosine curves |
| 650 |
in intervals that are multiples of $\pi/2$. |
| 651 |
|
| 652 |
\begin{command}{\pgfpathsine\marg{vector}} |
| 653 |
This command appends a sine curve in the interval $[0,\pi/2]$ to the |
| 654 |
current path. The sine curve is squeezed or stretched such that the curve |
| 655 |
starts at the current point and ends at the current point plus |
| 656 |
\meta{vector}. |
| 657 |
% |
| 658 |
\begin{codeexample}[] |
| 659 |
\begin{tikzpicture} |
| 660 |
\draw[help lines] (0,0) grid (3,1); |
| 661 |
\pgfpathmoveto{\pgfpoint{1cm}{0cm}} |
| 662 |
\pgfpathsine{\pgfpoint{1cm}{1cm}} |
| 663 |
\pgfusepath{stroke} |
| 664 |
|
| 665 |
\color{red} |
| 666 |
\pgfpathmoveto{\pgfpoint{1cm}{0cm}} |
| 667 |
\pgfpathsine{\pgfpoint{-2cm}{-2cm}} |
| 668 |
\pgfusepath{stroke} |
| 669 |
\end{tikzpicture} |
| 670 |
\end{codeexample} |
| 671 |
% |
| 672 |
The command will apply coordinate transformations and update the bounding |
| 673 |
boxes. |
| 674 |
\end{command} |
| 675 |
|
| 676 |
\begin{command}{\pgfpathcosine\marg{vector}} |
| 677 |
This command appends a cosine curve in the interval $[0,\pi/2]$ to the |
| 678 |
current path. The curve is squeezed or stretched such that the curve starts |
| 679 |
at the current point and ends at the current point plus \meta{vector}. |
| 680 |
Using several sine and cosine operations in sequence allows you to produce |
| 681 |
a complete sine or cosine curve |
| 682 |
% |
| 683 |
\begin{codeexample}[] |
| 684 |
\begin{pgfpicture} |
| 685 |
\pgfpathmoveto{\pgfpoint{0cm}{0cm}} |
| 686 |
\pgfpathsine{\pgfpoint{1cm}{1cm}} |
| 687 |
\pgfpathcosine{\pgfpoint{1cm}{-1cm}} |
| 688 |
\pgfpathsine{\pgfpoint{1cm}{-1cm}} |
| 689 |
\pgfpathcosine{\pgfpoint{1cm}{1cm}} |
| 690 |
\pgfsetfillcolor{yellow!80!black} |
| 691 |
\pgfusepath{fill,stroke} |
| 692 |
\end{pgfpicture} |
| 693 |
\end{codeexample} |
| 694 |
% |
| 695 |
The command will apply coordinate transformations and update the bounding |
| 696 |
boxes. |
| 697 |
\end{command} |
| 698 |
|
| 699 |
|
| 700 |
\subsection{Plot Path Operations} |
| 701 |
|
| 702 |
There exist several commands for appending plots to a path. These commands are |
| 703 |
available through the module |plot|. They are documented in |
| 704 |
Section~\ref{section-plots}. |
| 705 |
|
| 706 |
|
| 707 |
\subsection{Rounded Corners} |
| 708 |
|
| 709 |
Normally, when you connect two straight line segments or when you connect two |
| 710 |
curves that end and start ``at different angles'', you get ``sharp corners'' |
| 711 |
between the lines or curves. In some cases it is desirable to produce ``rounded |
| 712 |
corners'' instead. Thus, the lines or curves should be shortened a bit and then |
| 713 |
connected by arcs. |
| 714 |
|
| 715 |
\pgfname\ offers an easy way to achieve this effect, by calling the following |
| 716 |
two commands. |
| 717 |
|
| 718 |
\begin{command}{\pgfsetcornersarced\marg{point}} |
| 719 |
This command causes all subsequent corners to be replaced by little |
| 720 |
arcs. The effect of this command lasts till the end of the current |
| 721 |
\TeX\ scope. |
| 722 |
|
| 723 |
The \meta{point} dictates how large the corner arc will be. Consider a |
| 724 |
corner made by two lines $l$ and~$r$ and assume that the line $l$ comes |
| 725 |
first on the path. The $x$-dimension of the \meta{point} decides by how |
| 726 |
much the line~$l$ will be shortened, the $y$-dimension of \meta{point} |
| 727 |
decides by how much the line $r$ will be shortened. Then, the shortened |
| 728 |
lines are connected by an arc. |
| 729 |
% |
| 730 |
\begin{codeexample}[] |
| 731 |
\begin{tikzpicture} |
| 732 |
\draw[help lines] (0,0) grid (3,2); |
| 733 |
|
| 734 |
\pgfsetcornersarced{\pgfpoint{5mm}{5mm}} |
| 735 |
\pgfpathrectanglecorners{\pgfpointorigin}{\pgfpoint{3cm}{2cm}} |
| 736 |
\pgfusepath{stroke} |
| 737 |
\end{tikzpicture} |
| 738 |
\end{codeexample} |
| 739 |
|
| 740 |
\begin{codeexample}[] |
| 741 |
\begin{tikzpicture} |
| 742 |
\draw[help lines] (0,0) grid (3,2); |
| 743 |
|
| 744 |
\pgfsetcornersarced{\pgfpoint{10mm}{5mm}} |
| 745 |
% 10mm entering, |
| 746 |
% 5mm leaving. |
| 747 |
\pgfpathmoveto{\pgfpointorigin} |
| 748 |
\pgfpathlineto{\pgfpoint{0cm}{2cm}} |
| 749 |
\pgfpathlineto{\pgfpoint{3cm}{2cm}} |
| 750 |
\pgfpathcurveto |
| 751 |
{\pgfpoint{3cm}{0cm}} |
| 752 |
{\pgfpoint{2cm}{0cm}} |
| 753 |
{\pgfpoint{1cm}{0cm}} |
| 754 |
\pgfusepath{stroke} |
| 755 |
\end{tikzpicture} |
| 756 |
\end{codeexample} |
| 757 |
|
| 758 |
If the $x$- and $y$-coordinates of \meta{point} are the same and the corner |
| 759 |
is a right angle, you will get a perfect quarter circle (well, not quite |
| 760 |
perfect, but perfect up to six decimals). When the angle is not $90^\circ$, |
| 761 |
you only get a fair approximation. |
| 762 |
|
| 763 |
More or less ``all'' corners will be rounded, even the corner generated by |
| 764 |
a |\pgfpathclose| command. (The author is a bit proud of this feature.) |
| 765 |
% |
| 766 |
\begin{codeexample}[] |
| 767 |
\begin{pgfpicture} |
| 768 |
\pgfsetcornersarced{\pgfpoint{4pt}{4pt}} |
| 769 |
\pgfpathmoveto{\pgfpointpolar{0}{1cm}} |
| 770 |
\pgfpathlineto{\pgfpointpolar{72}{1cm}} |
| 771 |
\pgfpathlineto{\pgfpointpolar{144}{1cm}} |
| 772 |
\pgfpathlineto{\pgfpointpolar{216}{1cm}} |
| 773 |
\pgfpathlineto{\pgfpointpolar{288}{1cm}} |
| 774 |
\pgfpathclose |
| 775 |
\pgfusepath{stroke} |
| 776 |
\end{pgfpicture} |
| 777 |
\end{codeexample} |
| 778 |
|
| 779 |
To return to normal (unrounded) corners, use |
| 780 |
|\pgfsetcornersarced{\pgfpointorigin}|. |
| 781 |
|
| 782 |
Note that the rounding will produce strange and undesirable effects if the |
| 783 |
lines at the corners are too short. In this case the shortening may cause |
| 784 |
the lines to ``suddenly extend over the other end'' which is rarely |
| 785 |
desirable. |
| 786 |
\end{command} |
| 787 |
|
| 788 |
|
| 789 |
\subsection{Internal Tracking of Bounding Boxes for Paths and Pictures} |
| 790 |
\label{section-bb} |
| 791 |
|
| 792 |
\makeatletter |
| 793 |
|
| 794 |
The path construction commands keep track of two bounding boxes: One for the |
| 795 |
current path, which is reset whenever the path is used and thereby flushed, and |
| 796 |
a bounding box for the current |{pgfpicture}|. |
| 797 |
|
| 798 |
\begin{command}{\pgfresetboundingbox} |
| 799 |
Resets the picture's bounding box. The picture will simply forget any |
| 800 |
previous bounding box updates and start collecting from scratch. |
| 801 |
|
| 802 |
You can use this together with |\pgfusepath{use as bounding box}| to |
| 803 |
replace the bounding box by the one of a particular path (ignoring |
| 804 |
subsequent paths). |
| 805 |
\end{command} |
| 806 |
|
| 807 |
The bounding boxes are not accessible by ``normal'' macros. Rather, two sets of |
| 808 |
four dimension variables are used for this, all of which contain the |
| 809 |
letter~|@|. |
| 810 |
|
| 811 |
\begin{textoken}{\pgf@pathminx} |
| 812 |
The minimum $x$-coordinate ``mentioned'' in the current path. Initially, |
| 813 |
this is set to $16000$pt. |
| 814 |
\end{textoken} |
| 815 |
|
| 816 |
\begin{textoken}{\pgf@pathmaxx} |
| 817 |
The maximum $x$-coordinate ``mentioned'' in the current path. Initially, |
| 818 |
this is set to $-16000$pt. |
| 819 |
\end{textoken} |
| 820 |
|
| 821 |
\begin{textoken}{\pgf@pathminy} |
| 822 |
The minimum $y$-coordinate ``mentioned'' in the current path. Initially, |
| 823 |
this is set to $16000$pt. |
| 824 |
\end{textoken} |
| 825 |
|
| 826 |
\begin{textoken}{\pgf@pathmaxy} |
| 827 |
The maximum $y$-coordinate ``mentioned'' in the current path. Initially, |
| 828 |
this is set to $-16000$pt. |
| 829 |
\end{textoken} |
| 830 |
|
| 831 |
\begin{textoken}{\pgf@picminx} |
| 832 |
The minimum $x$-coordinate ``mentioned'' in the current picture. Initially, |
| 833 |
this is set to $16000$pt. |
| 834 |
\end{textoken} |
| 835 |
|
| 836 |
\begin{textoken}{\pgf@picmaxx} |
| 837 |
The maximum $x$-coordinate ``mentioned'' in the current picture. Initially, |
| 838 |
this is set to $-16000$pt. |
| 839 |
\end{textoken} |
| 840 |
|
| 841 |
\begin{textoken}{\pgf@picminy} |
| 842 |
The minimum $y$-coordinate ``mentioned'' in the current picture. Initially, |
| 843 |
this is set to $16000$pt. |
| 844 |
\end{textoken} |
| 845 |
|
| 846 |
\begin{textoken}{\pgf@picmaxy} |
| 847 |
The maximum $y$-coordinate ``mentioned'' in the current picture. Initially, |
| 848 |
this is set to $-16000$pt. |
| 849 |
\end{textoken} |
| 850 |
|
| 851 |
|
| 852 |
Each time a path construction command is called, the above variables are |
| 853 |
(globally) updated. To facilitate this, you can use the following command: |
| 854 |
|
| 855 |
\begin{command}{\pgf@protocolsizes\marg{x-dimension}\marg{y-dimension}} |
| 856 |
Updates all of the above dimensions in such a way that the point specified |
| 857 |
by the two arguments is inside both bounding boxes. For the picture's |
| 858 |
bounding box this updating occurs only if |\ifpgf@relevantforpicturesize| |
| 859 |
is true, see below. |
| 860 |
\end{command} |
| 861 |
|
| 862 |
For the bounding box of the picture it is not always desirable that every path |
| 863 |
construction command affects this bounding box. For example, if you have just |
| 864 |
used a clip command, you do not want anything outside the clipping area to |
| 865 |
affect the bounding box. For this reason, there exists a special ``\TeX\ if'' |
| 866 |
that (locally) decides whether updating should be applied to the picture's |
| 867 |
bounding box. Clipping will set this if to false, as will certain other |
| 868 |
commands. |
| 869 |
|
| 870 |
\begin{command}{\pgf@relevantforpicturesizefalse} |
| 871 |
Suppresses updating of the picture's bounding box. |
| 872 |
\end{command} |
| 873 |
|
| 874 |
\begin{command}{\pgf@relevantforpicturesizetrue} |
| 875 |
Causes updating of the picture's bounding box. |
| 876 |
\end{command} |