summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex737
1 files changed, 374 insertions, 363 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex
index eacaa4b84e8..4863835ddac 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex
@@ -12,13 +12,13 @@
\subsection{Overview}
-The ``basic entity of drawing'' in \pgfname\ is the \emph{path}. A
-path consists of several parts, each of which is either a closed or
-open curve. An open curve has a starting point and an end point and,
-in between, consists of several \emph{segments}, each of which is
-either a straight line or a B\'ezier curve. Here is an example of a
-path (in red) consisting of two parts, one open, one closed:
-
+The ``basic entity of drawing'' in \pgfname\ is the \emph{path}. A path
+consists of several parts, each of which is either a closed or open curve. An
+open curve has a starting point and an end point and, in between, consists of
+several \emph{segments}, each of which is either a straight line or a Bézier
+curve. Here is an example of a path (in red) consisting of two parts, one open,
+one closed:
+%
\begin{codeexample}[]
\begin{tikzpicture}[scale=2]
\draw[thick,red]
@@ -35,47 +35,47 @@ path (in red) consisting of two parts, one open, one closed:
\end{tikzpicture}
\end{codeexample}
-A path, by itself, has no ``effect,'' that is, it does not leave any
-marks on the page. It is just a set of points on the plane. However,
-you can \emph{use} a path in different ways. The most natural actions
-are \emph{stroking} (also known as \emph{drawing}) and
-\emph{filling}. Stroking can be imagined as picking up a pen of a
-certain diameter and ``moving it along the path.'' Filling means that
-everything ``inside'' the path is filled with a uniform
-color. Naturally, the open parts of a path must first be closed before
-a path can be filled.
-
-In \pgfname, there are numerous commands for constructing paths, all
-of which start with |\pgfpath|. There are also commands for
-\emph{using} paths, though most operations can be performed by calling
-|\pgfusepath| with an appropriate parameter.
-
-As a side-effect, the path construction commands keep track of two
-bounding boxes. One is the bounding box for the current path, the
-other is a bounding box for all paths in the current picture. See
-Section~\ref{section-bb} for more details.
-
-Each path construction command extends the current path in some
-way. The ``current path'' is a global entity that persists across
-\TeX\ groups. Thus, between calls to the path construction commands
-you can perform arbitrary computations and even open and close \TeX\
-groups. The current path only gets ``flushed'' when the |\pgfusepath|
-command is called (or when the soft-path subsystem is used directly,
-see Section~\ref{section-soft-paths}).
+A path, by itself, has no ``effect'', that is, it does not leave any marks on
+the page. It is just a set of points on the plane. However, you can \emph{use}
+a path in different ways. The most natural actions are \emph{stroking} (also
+known as \emph{drawing}) and \emph{filling}. Stroking can be imagined as
+picking up a pen of a certain diameter and ``moving it along the path''.
+Filling means that everything ``inside'' the path is filled with a uniform
+color. Naturally, the open parts of a path must first be closed before a path
+can be filled.
+
+In \pgfname, there are numerous commands for constructing paths, all of which
+start with |\pgfpath|. There are also commands for \emph{using} paths, though
+most operations can be performed by calling |\pgfusepath| with an appropriate
+parameter.
+
+As a side-effect, the path construction commands keep track of two bounding
+boxes. One is the bounding box for the current path, the other is a bounding
+box for all paths in the current picture. See Section~\ref{section-bb} for more
+details.
+
+Each path construction command extends the current path in some way. The
+``current path'' is a global entity that persists across \TeX\ groups. Thus,
+between calls to the path construction commands you can perform arbitrary
+computations and even open and close \TeX\ groups. The current path only gets
+``flushed'' when the |\pgfusepath| command is called (or when the soft-path
+subsystem is used directly, see Section~\ref{section-soft-paths}).
+
\subsection{The Move-To Path Operation}
-The most basic operation is the move-to operation. It must be given at
-the beginning of paths, though some path construction command (like
-|\pgfpathrectangle|) generate move-tos implicitly. A move-to operation
-can also be used to start a new part of a path.
+The most basic operation is the move-to operation. It must be given at the
+beginning of paths, though some path construction command (like
+|\pgfpathrectangle|) generate move-tos implicitly. A move-to operation can also
+be used to start a new part of a path.
\begin{command}{\pgfpathmoveto\marg{coordinate}}
- This command expects a \pgfname-coordinate like |\pgfpointorigin| as
- its parameter. When the current path is empty, this operation will
- start the path at the given \meta{coordinate}. If a path has already
- been partly constructed, this command will end the current part of
- the path and start a new one.
+ This command expects a \pgfname-coordinate like |\pgfpointorigin| as its
+ parameter. When the current path is empty, this operation will start the
+ path at the given \meta{coordinate}. If a path has already been partly
+ constructed, this command will end the current part of the path and start a
+ new one.
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfpathmoveto{\pgfpointorigin}
@@ -87,6 +87,7 @@ can also be used to start a new part of a path.
\pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfpathmoveto{\pgfpointorigin}
@@ -99,23 +100,25 @@ can also be used to start a new part of a path.
\pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
- The command will apply the current coordinate transformation matrix
- to \meta{coordinate} before using it.
+ %
+ The command will apply the current coordinate transformation matrix to
+ \meta{coordinate} before using it.
- It will update the bounding box of the current path and
- picture, if necessary.
+ It will update the bounding box of the current path and picture, if
+ necessary.
\end{command}
\subsection{The Line-To Path Operation}
\begin{command}{\pgfpathlineto\marg{coordinate}}
- This command extends the current path in a straight line to the
- given \meta{coordinate}. If this command is given at the beginning
- of path without any other path construction command given before (in
- particular without a move-to operation), the \TeX\ file may compile
- without an error message, but a viewer application may display an
- error message when trying to render the picture.
+ This command extends the current path in a straight line to the given
+ \meta{coordinate}. If this command is given at the beginning of path
+ without any other path construction command given before (in particular
+ without a move-to operation), the \TeX\ file may compile without an error
+ message, but a viewer application may display an error message when trying
+ to render the picture.
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfpathmoveto{\pgfpointorigin}
@@ -125,25 +128,26 @@ can also be used to start a new part of a path.
\pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
- The command will apply the current coordinate transformation matrix
- to \meta{coordinate} before using it.
+ %
+ The command will apply the current coordinate transformation matrix to
+ \meta{coordinate} before using it.
- It will update the bounding box of the current path and
- picture, if necessary.
+ It will update the bounding box of the current path and picture, if
+ necessary.
\end{command}
\subsection{The Curve-To Path Operations}
\begin{command}{\pgfpathcurveto\marg{support 1}\marg{support 2}\marg{coordinate}}
- This command extends the current path with a B\'ezier curve from the
- last point of the path to \meta{coordinate}. The \meta{support 1}
- and \meta{support 2} are the first and second support point of the
- B\'ezier curve. For more information on B\'ezier curves, please consult a
- standard textbook on computer graphics.
-
- Like the line-to command, this command may not be the first path
- construction command in a path.
+ This command extends the current path with a Bézier curve from the last
+ point of the path to \meta{coordinate}. The \meta{support 1} and
+ \meta{support 2} are the first and second support point of the Bézier
+ curve. For more information on Bézier curves, please consult a standard
+ textbook on computer graphics.
+
+ Like the line-to command, this command may not be the first path
+ construction command in a path.
\begin{codeexample}[]
\begin{pgfpicture}
\pgfpathmoveto{\pgfpointorigin}
@@ -153,23 +157,24 @@ can also be used to start a new part of a path.
\pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
- The command will apply the current coordinate transformation matrix
- to \meta{coordinate} before using it.
-
- It will update the bounding box of the current path and
- picture, if necessary. However, the bounding box is simply made
- large enough such that it encompasses all of the support points and
- the \meta{coordinate}. This will guarantee that the curve is
- completely inside the bounding box, but the bounding box will
- typically be quite a bit too large. It is not clear (to me) how this
- can be avoided without resorting to ``some serious math'' in order
- to calculate a precise bounding box.
+ %
+ The command will apply the current coordinate transformation matrix to
+ \meta{coordinate} before using it.
+
+ It will update the bounding box of the current path and picture, if
+ necessary. However, the bounding box is simply made large enough such that
+ it encompasses all of the support points and the \meta{coordinate}. This
+ will guarantee that the curve is completely inside the bounding box, but
+ the bounding box will typically be quite a bit too large. It is not clear
+ (to me) how this can be avoided without resorting to ``some serious math''
+ in order to calculate a precise bounding box.
\end{command}
\begin{command}{\pgfpathquadraticcurveto\marg{support}\marg{coordinate}}
- This command works like |\pgfpathcurveto|, only it uses a quadratic
- B\'ezier curve rather than a cubic one. This means that only one
- support point is needed.
+ This command works like |\pgfpathcurveto|, only it uses a quadratic Bézier
+ curve rather than a cubic one. This means that only one support point is
+ needed.
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfpathmoveto{\pgfpointorigin}
@@ -179,25 +184,23 @@ can also be used to start a new part of a path.
\pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
- Internally, the quadratic curve is converted into a cubic
- curve. The only noticeable effect of this is that the points used for
- computing the bounding box are the control points of the converted
- curve rather than \meta{support}. The main effect of this is that
- the bounding box will be a bit tighter than might be expected. In
- particular, \meta{support} will not always be part of the bounding
- box.
+ %
+ Internally, the quadratic curve is converted into a cubic curve. The only
+ noticeable effect of this is that the points used for computing the
+ bounding box are the control points of the converted curve rather than
+ \meta{support}. The main effect of this is that the bounding box will be a
+ bit tighter than might be expected. In particular, \meta{support} will not
+ always be part of the bounding box.
\end{command}
-
-There exist two commands to draw only part of a cubic B\'ezier curve:
+There exist two commands to draw only part of a cubic Bézier curve:
\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}}
-
- This command draws the part of the curve described by $p$, $s_1$,
- $s_2$ and $q$ between the times $t_1$ and $t_2$. A time value of 0
- indicates the point $p$ and a time value of 1 indicates point $q$.
- This command includes a moveto operation to the first point.
-
+ This command draws the part of the curve described by $p$, $s_1$, $s_2$ and
+ $q$ between the times $t_1$ and $t_2$. A time value of 0 indicates the
+ point $p$ and a time value of 1 indicates point $q$. This command includes
+ a moveto operation to the first point.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw [thin] (0,0) .. controls (0,2) and (3,0) .. (3,2);
@@ -209,23 +212,25 @@ There exist two commands to draw only part of a cubic B\'ezier curve:
\pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
\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}}
- This command works like |\pgfpathcurvebetweentime|, except that a
- moveto operation is \emph{not} made to the first point.
+ This command works like |\pgfpathcurvebetweentime|, except that a moveto
+ operation is \emph{not} made to the first point.
\end{command}
\subsection{The Close Path Operation}
\begin{command}{\pgfpathclose}
- This command closes the current part of the path by appending a
- straight line to the start point of the current part. Note that there
- \emph{is} a difference between closing a path and using the line-to
- operation to add a straight line to the start of the current
- path. The difference is demonstrated by the upper corners of the triangles
- in the following example:
+ This command closes the current part of the path by appending a straight
+ line to the start point of the current part. Note that there \emph{is} a
+ difference between closing a path and using the line-to operation to add a
+ straight line to the start of the current path. The difference is
+ demonstrated by the upper corners of the triangles in the following
+ example:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -241,30 +246,30 @@ There exist two commands to draw only part of a cubic B\'ezier curve:
\pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
\subsection{Arc, Ellipse and Circle Path Operations}
-The path construction commands that we have discussed up to now are
-sufficient to create all paths that can be created ``at all.''
-However, it is useful to have special commands to create certain
-shapes, like circles, that arise often in practice.
-
-In the following, the commands for adding (parts of) (transformed)
-circles to a path are described.
-
-\begin{command}{\pgfpatharc\marg{start angle}\marg{end
- angle}{\ttfamily\char`\{}\meta{radius}\opt{| and |\meta{y-radius}}{\ttfamily\char`\}}}
- This command appends a part of a circle (or an ellipse) to the current
- path. Imagine the curve between \meta{start angle} and \meta{end
- angle} on a circle of radius \meta{radius} (if $\meta{start angle}
- < \meta{end angle}$, the curve goes around the circle
- counterclockwise, otherwise clockwise). This curve is now moved such
- that the point where the curve starts is the previous last point of the
- path. Note that this command will \emph{not} start a new part of the
- path, which is important for example for filling purposes.
-
+The path construction commands that we have discussed up to now are sufficient
+to create all paths that can be created ``at all''. However, it is useful to
+have special commands to create certain shapes, like circles, that arise often
+in practice.
+
+In the following, the commands for adding (parts of) (transformed) circles to a
+path are described.
+
+\begin{command}{\pgfpatharc\marg{start angle}\marg{end angle}{\ttfamily\char`\{}\meta{radius}\opt{| and |\meta{y-radius}}{\ttfamily\char`\}}}
+ This command appends a part of a circle (or an ellipse) to the current
+ path. Imagine the curve between \meta{start angle} and \meta{end angle} on
+ a circle of radius \meta{radius} (if $\meta{start angle} < \meta{end
+ angle}$, the curve goes around the circle counterclockwise, otherwise
+ clockwise). This curve is now moved such that the point where the curve
+ starts is the previous last point of the path. Note that this command will
+ \emph{not} start a new part of the path, which is important for example for
+ filling purposes.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -277,14 +282,14 @@ circles to a path are described.
\end{tikzpicture}
\end{codeexample}
- Saying |\pgfpatharc{0}{360}{1cm}| ``nearly'' gives you a full
- circle. The ``nearly'' refers to the fact that the circle will not
- be closed. You can close it using |\pgfpathclose|.
-
- If the optional \meta{y-radius} is given, the \meta{radius} is the
- $x$-radius and the \meta{y-radius} the $y$-radius of the ellipse
- from which the curve is taken:
+ Saying |\pgfpatharc{0}{360}{1cm}| ``nearly'' gives you a full circle. The
+ ``nearly'' refers to the fact that the circle will not be closed. You can
+ close it using |\pgfpathclose|.
+ If the optional \meta{y-radius} is given, the \meta{radius} is the
+ $x$-radius and the \meta{y-radius} the $y$-radius of the ellipse from which
+ the curve is taken:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -294,11 +299,10 @@ circles to a path are described.
\end{tikzpicture}
\end{codeexample}
- The axes of the circle or ellipse from which the arc is ``taken''
- always point up and right. However, the current coordinate
- transformation matrix will have an effect on the arc. This can be
- used to, say, rotate an arc:
-
+ The axes of the circle or ellipse from which the arc is ``taken'' always
+ point up and right. However, the current coordinate transformation matrix
+ will have an effect on the arc. This can be used to, say, rotate an arc:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -309,22 +313,22 @@ circles to a path are described.
\end{tikzpicture}
\end{codeexample}
- The command will update the bounding box of the current path and
- picture, if necessary. Unless rotation or shearing transformations
- are applied, the bounding box will be tight.
+ The command will update the bounding box of the current path and picture,
+ if necessary. Unless rotation or shearing transformations are applied, the
+ bounding box will be tight.
\end{command}
-\begin{command}{\pgfpatharcaxes\marg{start angle}\marg{end
- angle}\marg{first axis}\marg{second axis}}
- This command is similar to |\pgfpatharc|. The main difference is how
- the ellipse or circle is specified from which the arc is taken. The
- two parameters \meta{first axis} and \meta{second axis} are the
- $0^\circ$-axis and the $90^\circ$-axis of the ellipse from which the
- path is taken. Thus, |\pgfpatharc{0}{90}{1cm and 2cm}| has the same effect
- as
+\begin{command}{\pgfpatharcaxes\marg{start angle}\marg{end angle}\marg{first axis}\marg{second axis}}
+ This command is similar to |\pgfpatharc|. The main difference is how the
+ ellipse or circle is specified from which the arc is taken. The two
+ parameters \meta{first axis} and \meta{second axis} are the $0^\circ$-axis
+ and the $90^\circ$-axis of the ellipse from which the path is taken. Thus,
+ |\pgfpatharc{0}{90}{1cm and 2cm}| has the same effect as
+ %
\begin{verbatim}
\pgfpatharcaxes{0}{90}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{2cm}}
\end{verbatim}
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -335,23 +339,22 @@ circles to a path are described.
\pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
-
-\begin{command}{\pgfpatharcto\marg{x-radius}\marg{y-radius}\marg{rotation}
- \marg{large arc flag}\marg{counterclockwise flag}\\\marg{target point}}
- This command (which directly corresponds to the arc-path command of
- \textsc{svg}) is used to add an arc to the path that starts at the
- current point and ends at \meta{target point}. This arc is part of
- an ellipse that is determined in the following way: Imagine an
- ellipse with radii \meta{x-radius} and \meta{y-radius} that is
- rotated around its center by \meta{rotation} degrees. When you move
- this ellipse around in the plane, there will be exactly two
- positions such that the two current point and the target point lie
- on the border of the ellipse (excluding pathological cases). The
- flags \meta{large arc flag} and \meta{clockwise flag} are then used to
- decide which of these ellipses should be picked and which arc on the
- picked ellipsis should be used.
+\begin{command}{\pgfpatharcto\marg{x-radius}\marg{y-radius}\marg{rotation} \marg{large arc flag}\marg{counterclockwise flag}\\\marg{target point}}
+ This command (which directly corresponds to the arc-path command of
+ \textsc{svg}) is used to add an arc to the path that starts at the current
+ point and ends at \meta{target point}. This arc is part of an ellipse that
+ is determined in the following way: Imagine an ellipse with radii
+ \meta{x-radius} and \meta{y-radius} that is rotated around its center by
+ \meta{rotation} degrees. When you move this ellipse around in the plane,
+ there will be exactly two positions such that the two current point and the
+ target point lie on the border of the ellipse (excluding pathological
+ cases). The flags \meta{large arc flag} and \meta{clockwise flag} are then
+ used to decide which of these ellipses should be picked and which arc on
+ the picked ellipsis should be used.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -361,14 +364,15 @@ circles to a path are described.
\pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}
- Both flags are considered to be false exactly if they evaluate to
- |0|, otherwise they are true. If the \meta{large arc flag} is true,
- then the angle spanned by the arc will be greater than $180^\circ$,
- otherwise it will be less than $180^\circ$. The \meta{clockwise
- flag} is used to determine which of the two ellipses should be
- used: if the flag is true, then the arc goes from the current point
- to the target point in a counterclockwise direction, otherwise in a
- clockwise fashion.
+ %
+ Both flags are considered to be false exactly if they evaluate to |0|,
+ otherwise they are true. If the \meta{large arc flag} is true, then the
+ angle spanned by the arc will be greater than $180^\circ$, otherwise it
+ will be less than $180^\circ$. The \meta{clockwise flag} is used to
+ determine which of the two ellipses should be used: if the flag is true,
+ then the arc goes from the current point to the target point in a
+ counterclockwise direction, otherwise in a clockwise fashion.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\pgfsetlinewidth{2pt}
@@ -394,21 +398,25 @@ circles to a path are described.
\pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
- \emph{Warning:} The internal computations necessary for this command
- are numerically very unstable. In particular, the arc will not
- always really end at the \meta{target coordinate}, but may be off by
- up to several points. A more precise positioning is currently
- infeasible due to \TeX's numerical weaknesses. The only case it
- works quite nicely is when the resulting angle is a multiple
- of~$90^\circ$.
+ %
+ \emph{Warning:} The internal computations necessary for this command are
+ numerically very unstable. In particular, the arc will not always really
+ end at the \meta{target coordinate}, but may be off by up to several
+ points. A more precise positioning is currently infeasible due to \TeX's
+ numerical weaknesses. The only case it works quite nicely is when the
+ resulting angle is a multiple of~$90^\circ$.
\end{command}
\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}}
- A specialized arc operation which is fast and numerically stable, provided a lot of information is given in advance.
+ A specialized arc operation which is fast and numerically stable, provided
+ a lot of information is given in advance.
- In contrast to |\pgfpatharc|, it explicitly interpolates start and end points.
+ In contrast to |\pgfpatharc|, it explicitly interpolates start and end
+ points.
- In contrast to |\pgfpatharcto|, this routine is numerically stable and quite fast since it relies on a lot of available information.
+ In contrast to |\pgfpatharcto|, this routine is numerically stable and
+ quite fast since it relies on a lot of available information.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -437,33 +445,31 @@ circles to a path are described.
\end{tikzpicture}
\end{codeexample}
- \begin{command}{\pgfpatharctomaxstepsize}
- The quality of arc approximation taken by
- |\pgfpatharctoprecomputed| by means of B\'ezier splines is
- controlled by a mesh width, which is initially
+ \begin{command}{\pgfpatharctomaxstepsize}
+ The quality of arc approximation taken by |\pgfpatharctoprecomputed| by
+ means of Bézier splines is controlled by a mesh width, which is
+ initially
- |\def\pgfpatharctoprecomputed{45}|.
+ |\def\pgfpatharctoprecomputed{45}|.
- The mesh width is provided in (full!) degrees. The smaller the mesh
- width, the more precise the arc approximation.
+ The mesh width is provided in (full!) degrees. The smaller the mesh
+ width, the more precise the arc approximation.
- Use an empty value to disable spline approximation (uses a single
- cubic polynomial for the complete arc).
+ Use an empty value to disable spline approximation (uses a single cubic
+ polynomial for the complete arc).
- The value must be an integer!
- \end{command}
+ The value must be an integer!
+ \end{command}
\end{command}
-\begin{command}{\pgfpathellipse\marg{center}\marg{first
- axis}\marg{second axis}}
- The effect of this command is to append an ellipse to the current
- path (if the path is not empty, a new part is started). The
- ellipse's center will be \meta{center} and \meta{first axis} and
- \meta{second axis} are the axis \emph{vectors}. The same effect as
- this command can also be achieved using an appropriate sequence of
- move-to, arc, and close operations, but this command is easier and
- faster.
-
+\begin{command}{\pgfpathellipse\marg{center}\marg{first axis}\marg{second axis}}
+ The effect of this command is to append an ellipse to the current path (if
+ the path is not empty, a new part is started). The ellipse's center will be
+ \meta{center} and \meta{first axis} and \meta{second axis} are the axis
+ \emph{vectors}. The same effect as this command can also be achieved using
+ an appropriate sequence of move-to, arc, and close operations, but this
+ command is easier and faster.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -479,35 +485,32 @@ circles to a path are described.
\end{tikzpicture}
\end{codeexample}
- The command will apply coordinate transformations to all coordinates
- of the ellipse. However, the coordinate transformations are applied
- only after the ellipse is ``finished conceptually.'' Thus, a
- transformation of 1cm to the right will simply shift the ellipse one
- centimeter to the right; it will not add 1cm to the $x$-coordinates
- of the two axis vectors.
+ The command will apply coordinate transformations to all coordinates of the
+ ellipse. However, the coordinate transformations are applied only after the
+ ellipse is ``finished conceptually''. Thus, a transformation of 1cm to the
+ right will simply shift the ellipse one centimeter to the right; it will
+ not add 1cm to the $x$-coordinates of the two axis vectors.
- The command will update the bounding box of the current path and
- picture, if necessary.
+ The command will update the bounding box of the current path and picture,
+ if necessary.
\end{command}
\begin{command}{\pgfpathcircle\marg{center}\marg{radius}}
- A shorthand for |\pgfpathellipse| applied to \meta{center} and the
- two axis vectors $(\meta{radius},0)$ and $(0,\meta{radius})$.
+ A shorthand for |\pgfpathellipse| applied to \meta{center} and the two axis
+ vectors $(\meta{radius},0)$ and $(0,\meta{radius})$.
\end{command}
\subsection{Rectangle Path Operations}
-Another shape that arises frequently is the rectangle. Two commands
-can be used to add a rectangle to the current path. Both commands will
-start a new part of the path.
-
+Another shape that arises frequently is the rectangle. Two commands can be used
+to add a rectangle to the current path. Both commands will start a new part of
+the path.
\begin{command}{\pgfpathrectangle\marg{corner}\marg{diagonal vector}}
- Adds a rectangle to the path whose one corner is \meta{corner} and
- whose opposite corner is given by $\meta{corner} + \meta{diagonal
- vector}$.
-
+ Adds a rectangle to the path whose one corner is \meta{corner} and whose
+ opposite corner is given by $\meta{corner} + \meta{diagonal vector}$.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -517,14 +520,15 @@ start a new part of the path.
\pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}
- The command will apply coordinate transformations and update the
- bounding boxes tightly.
+ %
+ The command will apply coordinate transformations and update the bounding
+ boxes tightly.
\end{command}
-
\begin{command}{\pgfpathrectanglecorners\marg{corner}\marg{opposite corner}}
- Adds a rectangle to the path whose two opposing corners are
- \meta{corner} and \meta{opposite corner}.
+ Adds a rectangle to the path whose two opposing corners are \meta{corner}
+ and \meta{opposite corner}.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -532,37 +536,40 @@ start a new part of the path.
\pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}
- The command will apply coordinate transformations and update the
- bounding boxes tightly.
+ %
+ The command will apply coordinate transformations and update the bounding
+ boxes tightly.
\end{command}
-
\subsection{The Grid Path Operation}
\begin{command}{\pgfpathgrid\oarg{options}\marg{first corner}\marg{second corner}}
- Appends a grid to the current path. That is, a (possibly large)
- number of parts are added to the path, each part consisting of a
- single horizontal or vertical straight line segment.
-
- Conceptually, the origin is part of the grid and the grid is clipped
- to the rectangle specified by the \meta{first corner} and
- the \meta{second corner}. However, no clipping occurs (this
- command just adds parts to the current path) and the points
- where the lines enter and leave the ``clipping area'' are computed
- and used to add simple lines to the current path.
-
- The following keys influence the grid:
- \begin{key}{/pgf/stepx=\meta{dimension} (initially 1cm)}
- The horizontal stepping.
- \end{key}
- \begin{key}{/pgf/stepy=\meta{dimension} (initially 1cm)}
- The vertical stepping.
- \end{key}
- \begin{key}{/pgf/step=\meta{vector}}
- Sets the horizontal stepping to the $x$-coordinate of
- \meta{vector} and the vertical stepping to its $y$-coordinate.
- \end{key}
+ Appends a grid to the current path. That is, a (possibly large) number of
+ parts are added to the path, each part consisting of a single horizontal or
+ vertical straight line segment.
+
+ Conceptually, the origin is part of the grid and the grid is clipped to the
+ rectangle specified by the \meta{first corner} and the \meta{second
+ corner}. However, no clipping occurs (this command just adds parts to the
+ current path) and the points where the lines enter and leave the ``clipping
+ area'' are computed and used to add simple lines to the current path.
+
+ The following keys influence the grid:
+ %
+ \begin{key}{/pgf/stepx=\meta{dimension} (initially 1cm)}
+ The horizontal stepping.
+ \end{key}
+ %
+ \begin{key}{/pgf/stepy=\meta{dimension} (initially 1cm)}
+ The vertical stepping.
+ \end{key}
+ %
+ \begin{key}{/pgf/step=\meta{vector}}
+ Sets the horizontal stepping to the $x$-coordinate of \meta{vector} and
+ the vertical stepping to its $y$-coordinate.
+ \end{key}
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfsetlinewidth{0.8pt}
@@ -575,9 +582,11 @@ start a new part of the path.
\pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
- The command will apply coordinate transformations and update the
- bounding boxes. As for ellipses, the transformations are
- applied to the ``conceptually finished'' grid.
+ %
+ The command will apply coordinate transformations and update the bounding
+ boxes. As for ellipses, the transformations are applied to the
+ ``conceptually finished'' grid.
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgftransformrotate{10}
@@ -585,27 +594,28 @@ start a new part of the path.
\pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
+ %
\end{command}
\subsection{The Parabola Path Operation}
\begin{command}{\pgfpathparabola\marg{bend vector}\marg{end vector}}
- This command appends two half-parabolas to the current path. The
- first starts at the current point and ends at the current point plus
- \meta{bend vector}. At this point, it has its bend. The second half
- parabola starts at that bend point and ends at point that is given by
- the bend plus \meta{end vector}.
-
- If you set \meta{end vector} to the null vector, you append only a
- half parabola that goes from the current point to the bend; by
- setting \meta{bend vector} to the null vector, you append only a
- half parabola that goes through the current point and \meta{end vector} and
- has its bend at the current point.
-
- It is not possible to use this command to draw a part of a parabola
- that does not contain the bend.
-
+ This command appends two half-parabolas to the current path. The first
+ starts at the current point and ends at the current point plus \meta{bend
+ vector}. At this point, it has its bend. The second half parabola starts at
+ that bend point and ends at point that is given by the bend plus \meta{end
+ vector}.
+
+ If you set \meta{end vector} to the null vector, you append only a half
+ parabola that goes from the current point to the bend; by setting
+ \meta{bend vector} to the null vector, you append only a half parabola that
+ goes through the current point and \meta{end vector} and has its bend at
+ the current point.
+
+ It is not possible to use this command to draw a part of a parabola that
+ does not contain the bend.
+ %
\begin{codeexample}[]
\begin{pgfpicture}
% Half-parabola going ``up and right''
@@ -627,22 +637,24 @@ start a new part of the path.
\pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
- The command will apply coordinate transformations and update the
- bounding boxes.
+ %
+ The command will apply coordinate transformations and update the bounding
+ boxes.
\end{command}
\subsection{Sine and Cosine Path Operations}
-Sine and cosine curves often need to be drawn and the following commands
-may help with this. However, they only allow you to append sine and
-cosine curves in intervals that are multiples of $\pi/2$.
+Sine and cosine curves often need to be drawn and the following commands may
+help with this. However, they only allow you to append sine and cosine curves
+in intervals that are multiples of $\pi/2$.
\begin{command}{\pgfpathsine\marg{vector}}
- This command appends a sine curve in the interval $[0,\pi/2]$ to the
- current path. The sine curve is squeezed or stretched such that the
- curve starts at the current point and ends at the current point plus
- \meta{vector}.
+ This command appends a sine curve in the interval $[0,\pi/2]$ to the
+ current path. The sine curve is squeezed or stretched such that the curve
+ starts at the current point and ends at the current point plus
+ \meta{vector}.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,1);
@@ -656,16 +668,18 @@ cosine curves in intervals that are multiples of $\pi/2$.
\pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
- The command will apply coordinate transformations and update the
- bounding boxes.
+ %
+ The command will apply coordinate transformations and update the bounding
+ boxes.
\end{command}
\begin{command}{\pgfpathcosine\marg{vector}}
- This command appends a cosine curve in the interval $[0,\pi/2]$ to the
- current path. The curve is squeezed or stretched such that the
- curve starts at the current point and ends at the current point plus
- \meta{vector}. Using several sine and cosine operations in sequence
- allows you to produce a complete sine or cosine curve
+ This command appends a cosine curve in the interval $[0,\pi/2]$ to the
+ current path. The curve is squeezed or stretched such that the curve starts
+ at the current point and ends at the current point plus \meta{vector}.
+ Using several sine and cosine operations in sequence allows you to produce
+ a complete sine or cosine curve
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfpathmoveto{\pgfpoint{0cm}{0cm}}
@@ -677,43 +691,42 @@ cosine curves in intervals that are multiples of $\pi/2$.
\pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
- The command will apply coordinate transformations and update the
- bounding boxes.
+ %
+ The command will apply coordinate transformations and update the bounding
+ boxes.
\end{command}
-
\subsection{Plot Path Operations}
-There exist several commands for appending
-plots to a path. These
-commands are available through the module |plot|. They are
-documented in Section~\ref{section-plots}.
+There exist several commands for appending plots to a path. These commands are
+available through the module |plot|. They are documented in
+Section~\ref{section-plots}.
\subsection{Rounded Corners}
-Normally, when you connect two straight line segments or when you
-connect two curves that end and start ``at different angles,'' you get
-``sharp corners'' between the lines or curves. In some cases it is
-desirable to produce ``rounded corners'' instead. Thus, the lines
-or curves should be shortened a bit and then connected by arcs.
+Normally, when you connect two straight line segments or when you connect two
+curves that end and start ``at different angles'', you get ``sharp corners''
+between the lines or curves. In some cases it is desirable to produce ``rounded
+corners'' instead. Thus, the lines or curves should be shortened a bit and then
+connected by arcs.
-\pgfname\ offers an easy way to achieve this effect, by calling the
-following two commands.
+\pgfname\ offers an easy way to achieve this effect, by calling the following
+two commands.
\begin{command}{\pgfsetcornersarced\marg{point}}
- This command causes all subsequent corners to be replaced by little
- arcs. The effect of this command lasts till the end of the current
- \TeX\ scope.
-
- The \meta{point} dictates how large the corner arc will be. Consider
- a corner made by two lines $l$ and~$r$ and assume that the line $l$
- comes first on the path. The $x$-dimension of the \meta{point}
- decides by how much the line~$l$ will be shortened, the
- $y$-dimension of \meta{point} decides by how much the line $r$ will
- be shortened. Then, the shortened lines are connected by an arc.
-
+ This command causes all subsequent corners to be replaced by little
+ arcs. The effect of this command lasts till the end of the current
+ \TeX\ scope.
+
+ The \meta{point} dictates how large the corner arc will be. Consider a
+ corner made by two lines $l$ and~$r$ and assume that the line $l$ comes
+ first on the path. The $x$-dimension of the \meta{point} decides by how
+ much the line~$l$ will be shortened, the $y$-dimension of \meta{point}
+ decides by how much the line $r$ will be shortened. Then, the shortened
+ lines are connected by an arc.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -742,15 +755,14 @@ following two commands.
\end{tikzpicture}
\end{codeexample}
- If the $x$- and $y$-coordinates of \meta{point} are the same and the
- corner is a right angle, you will get a perfect quarter circle
- (well, not quite perfect, but perfect up to six decimals). When the
- angle is not $90^\circ$, you only get a fair approximation.
-
- More or less ``all'' corners will be rounded, even the corner
- generated by a |\pgfpathclose| command. (The author is a bit proud
- of this feature.)
+ If the $x$- and $y$-coordinates of \meta{point} are the same and the corner
+ is a right angle, you will get a perfect quarter circle (well, not quite
+ perfect, but perfect up to six decimals). When the angle is not $90^\circ$,
+ you only get a fair approximation.
+ More or less ``all'' corners will be rounded, even the corner generated by
+ a |\pgfpathclose| command. (The author is a bit proud of this feature.)
+ %
\begin{codeexample}[]
\begin{pgfpicture}
\pgfsetcornersarced{\pgfpoint{4pt}{4pt}}
@@ -764,102 +776,101 @@ following two commands.
\end{pgfpicture}
\end{codeexample}
- To return to normal (unrounded) corners, use
- |\pgfsetcornersarced{\pgfpointorigin}|.
+ To return to normal (unrounded) corners, use
+ |\pgfsetcornersarced{\pgfpointorigin}|.
- Note that the rounding will produce strange and undesirable effects
- if the lines at the corners are too short. In this case the
- shortening may cause the lines to ``suddenly extend over the other
- end'' which is rarely desirable.
+ Note that the rounding will produce strange and undesirable effects if the
+ lines at the corners are too short. In this case the shortening may cause
+ the lines to ``suddenly extend over the other end'' which is rarely
+ desirable.
\end{command}
-
-
\subsection{Internal Tracking of Bounding Boxes for Paths and Pictures}
-
\label{section-bb}
\makeatletter
-The path construction commands keep track of two bounding boxes: One
-for the current path, which is reset whenever the path is used and
-thereby flushed, and a bounding box for the current |{pgfpicture}|.
+The path construction commands keep track of two bounding boxes: One for the
+current path, which is reset whenever the path is used and thereby flushed, and
+a bounding box for the current |{pgfpicture}|.
\begin{command}{\pgfresetboundingbox}
- Resets the picture's bounding box. The picture will simply forget any previous bounding box updates and start collecting from scratch.
-
- You can use this together with |\pgfusepath{use as bounding box}| to replace the bounding box by the one of a particular path (ignoring subsequent paths).
+ Resets the picture's bounding box. The picture will simply forget any
+ previous bounding box updates and start collecting from scratch.
+
+ You can use this together with |\pgfusepath{use as bounding box}| to
+ replace the bounding box by the one of a particular path (ignoring
+ subsequent paths).
\end{command}
-The bounding boxes are not accessible by ``normal'' macros. Rather,
-two sets of four dimension variables are used for this, all of which
-contain the letter~|@|.
+The bounding boxes are not accessible by ``normal'' macros. Rather, two sets of
+four dimension variables are used for this, all of which contain the
+letter~|@|.
\begin{textoken}{\pgf@pathminx}
- The minimum $x$-coordinate ``mentioned'' in the current
- path. Initially, this is set to $16000$pt.
+ The minimum $x$-coordinate ``mentioned'' in the current path. Initially,
+ this is set to $16000$pt.
\end{textoken}
\begin{textoken}{\pgf@pathmaxx}
- The maximum $x$-coordinate ``mentioned'' in the current
- path. Initially, this is set to $-16000$pt.
+ The maximum $x$-coordinate ``mentioned'' in the current path. Initially,
+ this is set to $-16000$pt.
\end{textoken}
\begin{textoken}{\pgf@pathminy}
- The minimum $y$-coordinate ``mentioned'' in the current
- path. Initially, this is set to $16000$pt.
+ The minimum $y$-coordinate ``mentioned'' in the current path. Initially,
+ this is set to $16000$pt.
\end{textoken}
\begin{textoken}{\pgf@pathmaxy}
- The maximum $y$-coordinate ``mentioned'' in the current
- path. Initially, this is set to $-16000$pt.
+ The maximum $y$-coordinate ``mentioned'' in the current path. Initially,
+ this is set to $-16000$pt.
\end{textoken}
\begin{textoken}{\pgf@picminx}
- The minimum $x$-coordinate ``mentioned'' in the current
- picture. Initially, this is set to $16000$pt.
+ The minimum $x$-coordinate ``mentioned'' in the current picture. Initially,
+ this is set to $16000$pt.
\end{textoken}
\begin{textoken}{\pgf@picmaxx}
- The maximum $x$-coordinate ``mentioned'' in the current
- picture. Initially, this is set to $-16000$pt.
+ The maximum $x$-coordinate ``mentioned'' in the current picture. Initially,
+ this is set to $-16000$pt.
\end{textoken}
\begin{textoken}{\pgf@picminy}
- The minimum $y$-coordinate ``mentioned'' in the current
- picture. Initially, this is set to $16000$pt.
+ The minimum $y$-coordinate ``mentioned'' in the current picture. Initially,
+ this is set to $16000$pt.
\end{textoken}
\begin{textoken}{\pgf@picmaxy}
- The maximum $y$-coordinate ``mentioned'' in the current
- picture. Initially, this is set to $-16000$pt.
+ The maximum $y$-coordinate ``mentioned'' in the current picture. Initially,
+ this is set to $-16000$pt.
\end{textoken}
-Each time a path construction command is called, the above variables
-are (globally) updated. To facilitate this, you can use the following
-command:
+Each time a path construction command is called, the above variables are
+(globally) updated. To facilitate this, you can use the following command:
\begin{command}{\pgf@protocolsizes\marg{x-dimension}\marg{y-dimension}}
- Updates all of the above dimensions in such a way that the point
- specified by the two arguments is inside both bounding boxes. For
- the picture's bounding box this updating occurs only if
- |\ifpgf@relevantforpicturesize| is true, see below.
+ Updates all of the above dimensions in such a way that the point specified
+ by the two arguments is inside both bounding boxes. For the picture's
+ bounding box this updating occurs only if |\ifpgf@relevantforpicturesize|
+ is true, see below.
\end{command}
-For the bounding box of the picture it is not always desirable that
-every path construction command affects this bounding box. For
-example, if you have just used a clip command, you do not want anything
-outside the clipping area to affect the bounding box. For this reason,
-there exists a special ``\TeX\ if'' that (locally) decides whether
-updating should be applied to the picture's bounding box. Clipping
-will set this if to false, as will certain other commands.
+For the bounding box of the picture it is not always desirable that every path
+construction command affects this bounding box. For example, if you have just
+used a clip command, you do not want anything outside the clipping area to
+affect the bounding box. For this reason, there exists a special ``\TeX\ if''
+that (locally) decides whether updating should be applied to the picture's
+bounding box. Clipping will set this if to false, as will certain other
+commands.
\begin{command}{\pgf@relevantforpicturesizefalse}
- Suppresses updating of the picture's bounding box.
+ Suppresses updating of the picture's bounding box.
\end{command}
\begin{command}{\pgf@relevantforpicturesizetrue}
- Causes updating of the picture's bounding box.
+ Causes updating of the picture's bounding box.
\end{command}