diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex | 441 |
1 files changed, 4 insertions, 437 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex index 37c0be02ec6..ea8d3f1bcb9 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex @@ -868,444 +868,11 @@ or cosine curve whose end points are not multiples of $\pi/2$. The |plot| operation can be used to append a line or curve to the path that goes through a large number of coordinates. These coordinates are -either given in a simple list of coordinates or they are read from -some file. - -The syntax of the |plot| comes in different versions. - -\begin{pathoperation}{--plot}{\meta{further arguments}} - This operation plots the curve through the coordinates specified in - the \meta{further arguments}. The current (sub)path is simply - continued, that is, a line-to operation to the first point of the - curve is implicitly added. The details of the \meta{further - arguments} will be explained in a moment. -\end{pathoperation} - -\begin{pathoperation}{plot}{\meta{further arguments}} - This operation plots the curve through the coordinates specified in - the \meta{further arguments} by first ``moving'' to the first - coordinate of the curve. -\end{pathoperation} - -The \meta{further arguments} are used in three different ways to -specifying the coordinates of the points to be plotted: - -\begin{enumerate} -\item - \opt{|--|}|plot|\oarg{local options}\declare{|coordinates{|\meta{coordinate - 1}\meta{coordinate 2}\dots\meta{coordinate $n$}|}|} -\item - \opt{|--|}|plot|\oarg{local options}\declare{|file{|\meta{filename}|}|} -\item - \opt{|--|}|plot|\oarg{local options}\declare{|function{|\meta{gnuplot formula}|}|} -\end{enumerate} - -These different ways are explained in the following. - - -\subsubsection{Plotting Points Given Inline} - -In the first two cases, the points are given directly in the \TeX-file -as in the following example: - -\begin{codeexample}[] -\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,1) (2,1) (10:2cm)}; -\end{codeexample} - -Here is an example showing the difference between |plot| and |--plot|: - -\begin{codeexample}[] -\begin{tikzpicture} - \draw (0,0) -- (1,1) plot coordinates {(2,0) (4,0)}; - \draw[color=red,xshift=5cm] - (0,0) -- (1,1) -- plot coordinates {(2,0) (4,0)}; -\end{tikzpicture} -\end{codeexample} - - -\subsubsection{Plotting Points Read From an External File} - -The second way of specifying points is to put them in an external -file named \meta{filename}. Currently, the only file format that -\tikzname\ allows is the following: Each line of the \meta{filename} -should contain one line starting with two numbers, separated by a -space. Anything following the two numbers on the line is -ignored. Also, lines starting with a |%| or a |#| are ignored as well -as empty lines. (This is exactly the format that \textsc{gnuplot} -produces when you say |set terminal table|.) If necessary, more -formats will be supported in the future, but it is usually easy to -produce a file containing data in this form. - -\begin{codeexample}[] -\tikz \draw plot[mark=x,smooth] file {plots/pgfmanual-sine.table}; -\end{codeexample} - -The file |plots/pgfmanual-sine.table| reads: -\begin{codeexample}[code only] -#Curve 0, 20 points -#x y type -0.00000 0.00000 i -0.52632 0.50235 i -1.05263 0.86873 i -1.57895 0.99997 i -... -9.47368 -0.04889 i -10.00000 -0.54402 i -\end{codeexample} -It was produced from the following source, using |gnuplot|: -\begin{codeexample}[code only] -set terminal table -set output "../plots/pgfmanual-sine.table" -set format "%.5f" -set samples 20 -plot [x=0:10] sin(x) -\end{codeexample} - -The \meta{local options} of the |plot| operation are local to each -plot and do not affect other plots ``on the same path.'' For example, -|plot[yshift=1cm]| will locally shift the plot 1cm upward. Remember, -however, that most options can only be applied to paths as a -whole. For example, |plot[red]| does not have the effect of making the -plot red. After all, you are trying to ``locally'' make part of the -path red, which is not possible. - -\subsubsection{Plotting a Function} -\label{section-tikz-gnuplot} - -Often, you will want to plot points that are given via a function like -$f(x) = x \sin x$. Unfortunately, \TeX\ does not really have enough -computational power to generate the points on such a function -efficiently (it is a text processing program, after all). However, -if you allow it, \TeX\ can try to call external programs that can -easily produce the necessary points. Currently, \tikzname\ knows how to -call \textsc{gnuplot}. - -When \tikzname\ encounters your operation -|plot[id=|\meta{id}|] function{x*sin(x)}| for -the first time, it will create a file called -\meta{prefix}\meta{id}|.gnuplot|, where \meta{prefix} is |\jobname.| by -default, that is, the name of you main |.tex| file. If no \meta{id} is -given, it will be empty, which is alright, but it is better when each -plot has a unique \meta{id} for reasons explained in a moment. Next, -\tikzname\ writes some initialization code into this file followed by -|plot x*sin(x)|. The initialization code sets up things -such that the |plot| operation will write the coordinates into another -file called \meta{prefix}\meta{id}|.table|. Finally, this table file -is read as if you had said |plot file{|\meta{prefix}\meta{id}|.table}|. - -For the plotting mechanism to work, two conditions must be met: -\begin{enumerate} -\item - You must have allowed \TeX\ to call external programs. This is often - switched off by default since this is a security risk (you might, - without knowing, run a \TeX\ file that calls all sorts of ``bad'' - commands). To enable this ``calling external programs'' a command - line option must be given to the \TeX\ program. Usually, it is - called something like |shell-escape| or |enable-write18|. For - example, for my |pdflatex| the option |--shell-escape| can be - given. -\item - You must have installed the |gnuplot| program and \TeX\ must find it - when compiling your file. -\end{enumerate} - -Unfortunately, these conditions will not always be met. Especially if -you pass some source to a coauthor and the coauthor does not have -\textsc{gnuplot} installed, he or she will have trouble compiling your -files. - -For this reason, \tikzname\ behaves differently when you compile your -graphic for the second time: If upon reaching -|plot[id=|\meta{id}|] function{...}| the file \meta{prefix}\meta{id}|.table| -already exists \emph{and} if the \meta{prefix}\meta{id}|.gnuplot| file -contains what \tikzname\ thinks that it ``should'' contain, the |.table| -file is immediately read without trying to call a |gnuplot| -program. This approach has the following advantages: -\begin{enumerate} -\item - If you pass a bundle of your |.tex| file and all |.gnuplot| and - |.table| files to someone else, that person can \TeX\ the |.tex| - file without having to have |gnuplot| installed. -\item - If the |\write18| feature is switched off for security reasons (a - good idea), then, upon the first compilation of the |.tex| file, the - |.gnuplot| will still be generated, but not the |.table| - file. You can then simply call |gnuplot| ``by hand'' for each - |.gnuplot| file, which will produce all necessary |.table| files. -\item - If you change the function that you wish to plot or its - domain, \tikzname\ will automatically try to regenerate the |.table| - file. -\item - If, out of laziness, you do not provide an |id|, the same |.gnuplot| - will be used for different plots, but this is not a problem since - the |.table| will automatically be regenerated for each plot - on-the-fly. \emph{Note: If you intend to share your files with - someone else, always use an id, so that the file can by typeset - without having \textsc{gnuplot} installed.} Also, having unique ids - for each plot will improve compilation speed since no external - programs need to be called, unless it is really necessary. -\end{enumerate} - -When you use |plot function{|\meta{gnuplot formula}|}|, the \meta{gnuplot - formula} must be given in the |gnuplot| syntax, whose details are -beyond the scope of this manual. Here is the ultra-condensed -essence: Use |x| as the variable and use the C-syntax for normal -plots, use |t| as the variable for parametric plots. Here are some examples: - -\begin{codeexample}[] -\begin{tikzpicture}[domain=0:4] - \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9); - - \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$}; - \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$}; - - \draw[color=red] plot[id=x] function{x} node[right] {$f(x) =x$}; - \draw[color=blue] plot[id=sin] function{sin(x)} node[right] {$f(x) = \sin x$}; - \draw[color=orange] plot[id=exp] function{0.05*exp(x)} node[right] {$f(x) = \frac{1}{20} \mathrm e^x$}; -\end{tikzpicture} -\end{codeexample} - - -The following options influence the plot: - -\begin{itemize} - \itemoption{samples}|=|\meta{number} - sets the number of samples used in the plot. The default is 25. - \itemoption{domain}|=|\meta{start}|:|\meta{end} - sets the domain between which the samples are taken. The default is - |-5:5|. - \itemoption{parametric}\opt{|=|\meta{true or false}} - sets whether the plot is a parametric plot. If true, then |t| must - be used instead of |x| as the parameter and two comma-separated - functions must be given in the \meta{gnuplot formula}. An example is - the following: -\begin{codeexample}[] -\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth] - plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)}; -\end{codeexample} - - \itemoption{id}|=|\meta{id} - sets the identifier of the current plot. This should be a unique - identifier for each plot (though things will also work if it is not, - but not as well, see the explanations above). The \meta{id} will be - part of a filename, so it should not contain anything fancy like |*| - or |$|.%$ - \itemoption{prefix}|=|\meta{prefix} - is put before each plot file name. The default is |\jobname.|, but - if you have many plots, it might be better to use, say |plots/| and - have all plots placed in a directory. You have to create the - directory yourself. - \itemoption{raw gnuplot} - causes the \meta{gnuplot formula} to be passed on to - \textsc{gnuplot} without setting up the samples or the |plot| - operation. Thus, you could write -\begin{codeexample}[code only] -plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)} -\end{codeexample} - This can be - useful for complicated things that need to be passed to - \textsc{gnuplot}. However, for really complicated situations you - should create a special external generating \textsc{gnuplot} file - and use the |file|-syntax to include the table ``by hand.'' -\end{itemize} - -The following styles influence the plot: -\begin{itemize} - \itemstyle{every plot} - This style is installed in each plot, that is, as if you always said -\begin{codeexample}[code only] - plot[style=every plot,...] -\end{codeexample} - This is most useful for globally setting a prefix for all plots by saying: -\begin{codeexample}[code only] -\tikzstyle{every plot}=[prefix=plots/] -\end{codeexample} -\end{itemize} - - - -\subsubsection{Placing Marks on the Plot} - -As we saw already, it is possible to add \emph{marks} to a plot using -the |mark| option. When this option is used, a copy of the plot -mark is placed on each point of the plot. Note that the marks are -placed \emph{after} the whole path has been drawn/filled/shaded. In -this respect, they are handled like text nodes. - -In detail, the following options govern how marks are drawn: -\begin{itemize} - \itemoption{mark}|=|\meta{mark mnemonic} - Sets the mark to a mnemonic that has previously been defined using - the |\pgfdeclareplotmark|. By default, |*|, |+|, and |x| are available, - which draw a filled circle, a plus, and a cross as marks. Many more - marks become available when the library |pgflibraryplotmarks| is - loaded. Section~\ref{section-plot-marks} lists the available plot - marks. - - One plot mark is special: the |ball| plot mark is available only - it \tikzname. The |ball color| determines the balls's color. Do not use - this option with a large number of marks since it will take very long - to render in PostScript. - - \begin{tabular}{lc} - Option & Effect \\\hline \vrule height14pt width0pt - \plotmarkentrytikz{ball} - \end{tabular} - - \itemoption{mark repeat}|=|\meta{r} - This option tells \tikzname\ that only every $r$th mark should be - drawn. - -\begin{codeexample}[] -\tikz \draw plot[mark=x,mark repeat=3,smooth] file {plots/pgfmanual-sine.table}; -\end{codeexample} - - \itemoption{mark phase}|=|\meta{p} - This option tells \tikzname\ that the first mark to be draw should - be the $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so - on. - -\begin{codeexample}[] -\tikz \draw plot[mark=x,mark repeat=3,mark phase=6,smooth] file {plots/pgfmanual-sine.table}; -\end{codeexample} - - \itemoption{mark indices}|=|\meta{list} - This option allows you to specify explicitly the indices at which a - mark should be placed. Counting starts with 1. You can use the - |\foreach| syntax, that is, |...| can be used. - -\begin{codeexample}[] -\tikz \draw plot[mark=x,mark indices={1,4,...,10,11,12,...,16,20},smooth] - file {plots/pgfmanual-sine.table}; -\end{codeexample} - - \itemoption{mark size}|=|\meta{dimension} - Sets the size of the plot marks. For circular plot marks, - \meta{dimension} is the radius, for other plot marks - \meta{dimension} should be about half the width and height. - - This option is not really necessary, since you achieve the same - effect by specifying |scale=|\meta{factor} as a local option, where - \meta{factor} is the quotient of the desired size and the default - size. However, using |mark size| is a bit faster and more natural. - - \itemoption{mark options}|=|\meta{options} - These options are applied to marks when they are drawn. For example, - you can scale (or otherwise transform) the plot mark or set its - color. -\begin{codeexample}[] -\tikz \fill[fill=blue!20] - plot[mark=triangle*,mark options={color=blue,rotate=180}] - file{plots/pgfmanual-sine.table} |- (0,0); -\end{codeexample} -\end{itemize} - - - -\subsubsection{Smooth Plots, Sharp Plots, and Comb Plots} - -There are different things the |plot| operation can do with the points -it reads from a file or from the inlined list of points. By default, -it will connect these points by straight lines. However, you can also -use options to change the behavior of |plot|. - -\begin{itemize} - \itemoption{sharp plot} - This is the default and causes the points to be connected by - straight lines. This option is included only so that you can - ``switch back'' if you ``globally'' install, say, |smooth|. - - \itemoption{smooth} - This option causes the points on the path to be connected using a - smooth curve: - -\begin{codeexample}[] -\tikz\draw plot[smooth] file{plots/pgfmanual-sine.table}; -\end{codeexample} - - Note that the smoothing algorithm is not very intelligent. You will - get the best results if the bending angles are small, that is, less - than about $30^\circ$ and, even more importantly, if the distances - between points are about the same all over the plotting path. - - \itemoption{tension}|=|\meta{value} - This option influences how ``tight'' the smoothing is. A lower value - will result in sharper corners, a higher value in more ``round'' - curves. A value of $1$ results in a circle if four points at - quarter-positions on a circle are given. The default is $0.55$. The - ``correct'' value depends on the details of plot. - -\begin{codeexample}[] -\begin{tikzpicture}[smooth cycle] - \draw plot[tension=0.2] - coordinates{(0,0) (1,1) (2,0) (1,-1)}; - \draw[yshift=-2.25cm] plot[tension=0.5] - coordinates{(0,0) (1,1) (2,0) (1,-1)}; - \draw[yshift=-4.5cm] plot[tension=1] - coordinates{(0,0) (1,1) (2,0) (1,-1)}; -\end{tikzpicture} -\end{codeexample} - - \itemoption{smooth cycle} - This option causes the points on the path to be connected using a - closed smooth curve. - -\begin{codeexample}[] -\tikz[scale=0.5] - \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)} - plot coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle; -\end{codeexample} - - \itemoption{ycomb} - This option causes the |plot| operation to interpret the plotting - points differently. Instead of connecting them, for each point of - the plot a straight line is added to the path from the $x$-axis to the point, - resulting in a sort of ``comb'' or ``bar diagram.'' - -\begin{codeexample}[] -\tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table}; -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture}[ycomb] - \draw[color=red,line width=6pt] - plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)}; - \draw[color=red!50,line width=4pt,xshift=3pt] - plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)}; -\end{tikzpicture} -\end{codeexample} - - \itemoption{xcomb} - This option works like |ycomb| except that the bars are horizontal. - -\begin{codeexample}[] -\tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)}; -\end{codeexample} - - \itemoption{polar comb} - This option causes a line from the origin to the point to be added - to the path for each plot point. - -\begin{codeexample}[] -\tikz \draw plot[polar comb, - mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt] - coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)}; -\end{codeexample} - - - \itemoption{only marks} - This option causes only marks to be shown; no path segments are - added to the actual path. This can be useful for quickly adding some - marks to a path. - -\begin{codeexample}[] -\tikz \draw (0,0) sin (1,1) cos (2,0) - plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)}; -\end{codeexample} -\end{itemize} - +either given in a simple list of coordinates, read from some file, or +they are computed on the fly. +Since the syntax and the behaviour of this command are a bit complex, +they are described in the separated Section~\ref{section-tikz-plots}. \subsection{The To Path Operation} |