diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex | 206 |
1 files changed, 195 insertions, 11 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex index cf23448973a..54acad0f01b 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex @@ -3,21 +3,36 @@ \tikzset{external/figure name/.add={}{patchplot_}}% \label{sec:lib:patchplots} \begin{pgfplotslibrary}{patchplots} - A library for advanced |patch| plots. It has been designed to visualize shaded isoparametric finite element meshes of higher order. Its core is an interface to the generation of smoothly shaped elements with interpolated color values (based on \texttt{.pdf} Shading Type 6 and \texttt{.pdf} Shading Type 7), with additional (limited) support for constant color filling without shadings. + A library for advanced |patch| plots. Its strength is the creation of patches with smooth boundaries and smoothly shaded colors. + + A |patch| plot is a plot in which each individual patch is available. Here, ``available'' means that the user provided each individual patch manually. This can be achieved by means of a long series of patches which have been concatenated in a suitable way (compare the description of |patch| plots in section~\ref{sec:pgfplots:3d:patch}) or by means of a mathematical expression which is sampled (compare the key |patch type sampling|). Most |patch type|s expect a series of point evaluations in a specific sequence. + + Note that even though each individual patch might have a smooth boundary, the |patchplots| library \emph{does not interpolate smoothly between adjacent patches}. Consequently, it is task of the one who creates the patches (which means: evaluated some function at its vertices) to ensure that patches can be glued together in an adequate way. This allows a lot of freedom, including both jumps and smoothly concatenated edges. + + The |patchplots| library comes with a couple of inherently two--dimensional |patch type|s (including second order triangles/rectangular patches and cubic tensor product patches known for finite elements). Typically, these patches live in a three--dimensional axis. Often, they are used to visualize the surface of function values $f(x,y)$. The |patchplots| library ensures that such patches are drawn in a way which respects the current view. In particular, if a patch folds over itsself (which is possible), it is drawn such that foreground areas are in the foreground and background areas are in the background. + + The |patchplots| library comes with smoothly shaded patches. More precisely, both the boundary of patches and their color shading are smooth. Note, however, that the patch boundary typically has much more smoothness than the color shading. + + The |patchplots| library also allows automatic conversion from a higher--order patch to triangles (triangulation) by means of the key |patch to triangles|. Furthermore, it features automatic |patch refines|. + + Use the |patchplots| library if you want to have smooth boundaries for your patches, or if you need advanced shadings, or if you want polygon plots, or if you want more freedom in one--dimensional patches. -\subsubsection{Additional Patch Types} \message{Underfull hbox is OK.^^J}% -\begin{pgfplotskey}{patch type=\mchoice{default,rectangle,triangle,line,quadratic spline,cubic spline,\\bilinear,triangle quadr,biquadratic,coons,polygon,tensor bezier} (initially default)} +\begin{pgfplotskey}{patch type=\mchoice{default,rectangle,triangle,line,quadratic spline,cubic spline,\\bilinear,triangle quadr,biquadratic,bicubic,polygon,coons,tensor bezier} (initially default)} The |patchplots| library supports several new |patch type|s in addition to the initially available choices (which are |rectangle|,|triangle| and |line|). The documentation of the two--dimensional choices from page~\pageref{key:patch:type} is repeated here. - There are two new one--dimensional patch types, namely |quadratic spline| and |cubic spline|. Here, |patch type=quadratic spline| consists of quadratic patches of $n=3$ vertices each. The vertices are interpolated exactly: + The new |patch type|s are discussed in detail on the following pages. +\end{pgfplotskey} % end the environment to simplify sectioning. + +\subsubsection{One--Dimensional Patch Types} + There are two new one--dimensional patch types, namely |quadratic spline| and |cubic spline|. Here, |patch type=|\declareandlabel{quadratic spline} consists of quadratic patches of $n=3$ vertices each. The vertices are interpolated exactly: \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[nodes near coords={(\coordindex)}, title={\texttt{patch type=quadratic spline}}] \addplot[ mark=*, - patch,mesh,% without mesh, pgfplots tries to fill + patch, patch type=quadratic spline] coordinates { % left, right, middle-> first segment @@ -30,14 +45,14 @@ coordinates { \end{codeexample} \noindent In our example, the first segment interpolates $f(x)=x^2$ at the points $\{0,\nicefrac12,1\}$. The |quadratic spline| is actually nothing but piecewise Lagrangian interpolation with quadratic polynomials: it expects three points in the sequence `(left end), (right end), (middle)' and interpolates these three points with a quadratic polynomial. Unlike the default 1d |mesh| visualization (which uses |patch type=line| implicitly), you have to use the special syntax above (or the equivalent approach by means of |patch table|). Note that |patch type=quadratic spline| results in correct shapes, but uses \emph{just constant color} for each segment; high--order color shading is only supported approximately using |patch refines|. - The |patch type=cubic spline| is very similar: it expects patches of $n=4$ vertices and interpolates them with a cubic polynomial: + The |patch type=|\declareandlabel{cubic spline} is very similar: it expects patches of $n=4$ vertices and interpolates them with a cubic polynomial: \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[nodes near coords={(\coordindex)}, title={\texttt{patch type=cubic spline}}] \addplot[ mark=*, - patch,mesh, + patch, patch type=cubic spline] coordinates { % left, right, left middle, right middle @@ -51,7 +66,141 @@ coordinates { \end{codeexample} \noindent Here, we interpolated $f(x)=x^3$ at the four equidistant points $\{-1,-\nicefrac13,\nicefrac13,1\}$ with a cubic polynomial (which is $x^3$). The |cubic spline| expects a sequence of patches, each with four coordinates, given in the sequence `(left end), (right end), (interpolation point at $\nicefrac13$), (interpolation point at $\nicefrac23$)'. It has limitations and features like |quadratic spline|, see above. +\subsubsection{Providing Patches by means of Mathematical Expressions} + Most |patch type|s expect a specific number of vertices in a specific sequence. This is part of what the |patchplots| library is. But is is still tedious to provide this sort of data. + + For simple |patch type|s like |line,rectangle| and |bilinear|, you can provide the input coordinates with any of the input methods which are available for all other plot handlers. In particular, |line| is just a |sharp plot| (with individually colored segments) and |rectangle| is nothing but a |surf| plot. Note that both |rectangle| and |bilinear| also accept the standard matrix input (with scanlines, see |mesh/ordering| and its documentation). In summary: \emph{simple patch types accept a simple input format}. + +\begin{pgfplotskey}{patch type sampling=\mchoice{true,false} (initially false)} + There are some complicated |patch type|s. In particular, all |patch type|s of higher order (i.e.\ \verbpdfref{quadratic spline}, \verbpdfref{cubic spline}, \verbpdfref{triangle quadr}, |biquadratic|, |bicubic|) need more points than just their corners. For such patch types, you need to resort to |mesh input=patches|. That means you need to provide extra vertices and their function evaluation values in a specific sequence. + + The |patch type sampling| method allows to simplify the procedure for such complicated |patch type|s\footnote{Note that \texttt{patch type sampling} is more or less useless for simple patch types.}: it works together with |\addplot expression| and evaluates the mathematical expression at each of the required vertices (in the correct sequence): +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot[ + samples=5,domain=-3:3, + mesh,patch type=cubic spline, + patch type sampling, + % avoid individual colors per segment: + blue,point meta=none, + ] + {exp(-x^2)}; + + % a second plot which shows the + % generated x positions: + \addplot[ + mark=*,only marks,scatter, + samples=5,domain=-3:3, + patch type=cubic spline, + patch type sampling, + point meta={exp(-x^2)}, + ] + {-0.1}; + + % a third plot which shows the marks + % without patch type sampling: + \addplot[ + mark=*,only marks,scatter, + samples=5,domain=-3:3, + point meta={exp(-x^2)}, + ] + {-0.15}; + + \end{axis} +\end{tikzpicture} +\end{codeexample} + \noindent The first plot above is almost a normal plot by expression. The |samples| and |domain| key controls the sampling procedure, and |blue,point meta=none| defines the global color to use. Note that the special choice |point meta=none| simply disables individual colors per mesh segment (which is the default for |mesh| plots). However, the |patch type sampling| key here makes a huge difference: it tells \PGFPlots\ to check the current value of |patch type| and to sample a coordinate sequence which is suitable as input for that |patch type|. We see that the outcome is a partially smooth function (more about that below). + + The method |patch type sampling| samples |x| just as usual. The result is a sequence $[x_0,x_1,\dotsc,x_k]$. For each interval $[x_i,x_{i+1}]$, a |patch type| is sampled inside of the interval. To this end, the current |patch type| is used to generate a standardized vertex pattern in the unit cube. For |patch type=cubic spline|, this generates four points $0, \nicefrac13, \nicefrac23, 1$. These standardized numbers are mapped into $[x_i, x_{i+1}]$. Then, any mathematical expressions (in our case |exp(-x^2)|) are evaluated at the resulting positions. + + The second plot in our example above shows the |mark|ers resulting from |patch type sampling|. Note that we see $13$ markers even though we have said |samples=5|. These $5$ samples are shown in the third plot. This is because |patch type=cubic spline| needs $4$ points for each patch (i.e.\ $4$ points in each sampled interval). + + Note that even though the result in our example above is \emph{partially} smooth, it is \emph{not} globally smooth. In other words: each resulting mesh segment is a polynomial of third order. But: the five cubic polynomials are determined independently; and they are simple glued together without any intelligence. In particular, they are \emph{unsmooth} at the five initial sampling points! This key cannot apply global smoothing. It is really just a convenient method which simplifies sampling of such patch types. + + The method |patch type sampling| can also be used for |surf| plots, i.e.\ for matrix sampling. It works in the same way: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot3[surf,shader=interp, + patch type=bicubic, + patch type sampling, + samples=5,domain=-3:3] + {exp(-x^2-y^2)}; + + % show the generated grid on top: + \addplot3[ + mark=*,mark size=1pt,only marks,scatter, + samples=5,domain=-3:3, + patch type=bicubic, + patch type sampling, + point meta={exp(-x^2-y^2)}, + ] + {1.1}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + The example is similar to our one--dimensional example above: it uses the same 1d function as product. We see that it has $13^2$ samples instead of just $5^2$, and we see that the geometry is partially smooth (see above for ``partially''). Note, however, that the color interpolation is only applied once per patch. The following example shows a |bilinear| patch with unsmooth geometry, but higher resolution for the color data, on a $13\times13$ mesh: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot3[surf,shader=interp, + patch type=bilinear, + samples=13,domain=-3:3] + {exp(-x^2-y^2)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + Note that you may want to view the preceding examples in Acrobat Reader. Many free pdf viewers cannot display these shadings properly. +\end{pgfplotskey} + +\subsubsection{Global One--Dimensional Curves with Smooth Splines} +\index{point meta!point meta=none for smooth patch plots} +Typically, \PGFPlots\ assumes that you want individually colored patch segments whenever you use one of the plot handlers |mesh|, |surf|, or |patch|. The individual colors are determined by the current |colormap| and the value of |point meta| (compare section~\ref{pgfplots:point:meta}). +Technically, individually colored path segments are one unit. If you |fill| them, you fill only one segment. You cannot fill them against the axis. In particular, you cannot use |\closedcycle| for individually colored |mesh| or |patch| plots. +\index{closedcycle!Mesh or patch plots}% +\index{mesh!closedcycle}% +\index{patch!closedcycle}% + +The |patchplots| library comes with one--dimensional |patch type|s like \verbpdfref{quadratic spline} or \verbpdfref{cubic spline}. It would be useful to draw a global path, that is: one which has a single color such that |\closedcycle| works. This is supported if you write |point meta=none|: +\index{mesh!point meta=none and global paths}% +\index{surf!point meta=none and global paths}% +\index{patch!point meta=none and global paths}% +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + axis lines=middle, + axis on top, + enlargelimits, + title={Global path with + \texttt{cubic spline}}] +\addplot[ + mark=*, + patch, + patch type=cubic spline, + point meta=none,% allow \closedcycle + blue, + fill=blue!60!black, +] +table { + % left, right, left middle, right middle + -1 -1 + 1 1 + -0.333333 -0.037037 + 0.333333 +0.037037 + + 1 1 + 2 -0.5 + 1.333333 1.5 + 1.666666 1 +} +\closedcycle; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\subsubsection{Two--Dimensional Patch Types} The |patchplots| library is especially strong for |shader=interp|, so this is our main focus in the remaining documentation here. \paragraph{Attention:} At the time of this writing, many free pdf viewers do not fully support the following shadings\footnote{The author of this package has submitted bugfixes to Linux viewers based on xpdf/libpoppler, so the problem will (hopefully) vanish in future versions.}. The preferred viewer is Adobe Acrobat Reader. @@ -202,8 +351,44 @@ coordinates { \end{axis} \end{tikzpicture} \end{codeexample} - \noindent We see that the shape's boundary is reconstructed exactly using the |biquadratic| patch. In addition, |patch refines| improves the (first order) color interpolation. Details for |patch refines| are discussed in Section~\ref{sec:lib:patchplots:refinement} abd details and limitations regarding superimposed grid lines are discussed in Section~\ref{sec:lib:patchplots:grids}. + \noindent We see that the shape's boundary is reconstructed exactly using the |biquadratic| patch. In addition, |patch refines| improves the (first order) color interpolation. Details for |patch refines| are discussed in Section~\ref{sec:lib:patchplots:refinement} and details and limitations regarding superimposed grid lines are discussed in Section~\ref{sec:lib:patchplots:grids}. + The choice \declareandlabel{bicubic} is similar to |biquadratic|: it allows to defines two--dimensional patches whose boundary is defined by four cubic polynomials. Consequently, it allows very smooth boundaries -- especially since the viewer constructs these boundaries at every zoom level. A |bicubic| patch is constructed from $16$ points which are arranged in a $4\times4$ matrix. Each consecutive $16$ points make up a single |bicubic| patch. The $17$th point starts the next |bicubic| patch (just as for any other |patch type|). +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[nodes near coords={(\coordindex)}, + title=Single Bicubic Quadrilateral] +\addplot3[patch,patch type=bicubic,shader=interp] +coordinates { + (0,0,1) (1,0,0) (2,0,0) (3,0,0) + (0,1,0) (1,1,0) (2,1,0) (3,1,0) + (0,2,0) (1,2,0) (2,2,0) (3,2,0) + (0,3,0) (1,3,0) (2,3,0) (3,3,0) +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + Just as for |biquadratic|, the color interpolation of |bicubic| is (just) bilinear, even though the geometry is of higher order. The color interpolation uses the |point meta| values determined at the four corners of each patch; all other values of |point meta| are ignored by the shader (although their values are used to compute |point meta min| and |point meta max|). +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title=Two Bicubic Patches] +\addplot3[patch,patch type=bicubic,shader=interp,point meta=explicit] +coordinates { + (0,0,1)[1] (1,0,0)[0] (2,0,0)[0] (3,0,0)[0] + (0,1,0)[0] (1,1,0)[0] (2,1,0)[0] (3,1,0)[0] + (0,2,0)[0] (1,2,0)[0] (2,2,0)[0] (3,2,0)[0] + (0,3,0)[0] (1,3,0)[0] (2,3,0)[0] (3,3,0)[0] + + (3,0,0)[0] (4,0,0)[0] (5,0,0)[0] (6,0,0)[0.7] + (3,1,0)[0] (4,1,.5)[1](5,1,0)[0] (6,1,0)[0] + (3,2,0)[0] (4,2,0)[0] (5,2,0)[0] (6,2,0)[0] + (3,3,0)[0] (4,3,0)[0] (5,3,0)[0] (6,3,0)[0.1] +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + The previous example uses two patches of type |bicubic|. Note that the color data (|point meta|) has been provided explicitly -- and its values are only used at the corners (the |[1]| value after the point |(4,1,.5)| is ignored). Color interpolation of |bicubic| patches uses only the color data at the patch's corners. The remaining color data values are ignored. Note that if you leave the default (which is |point meta=f(x)| instead of |point meta=explicit|), the second patch will be blue. This is because the four corner vertices of the second patch define the color shading -- and their $z$ value is~$0$. The choice \declareandlabel{coons} expects a sequence of one or more Coons patches, made up of $n=12$ points each. A Coons patch is delimited by four cubic B\'ezier curves, with the end points attached to each other -- and the $n$ points provide the required control points for these curves in a specific ordering which is illustrated in the following example: \begin{codeexample}[] @@ -237,7 +422,7 @@ coordinates { Even for two dimensions, Coons patches may fold over themselves. To determine which part is foreground and which part is background, the following rule applies: the four corner points $(0)$, $(3)$, $(6)$, $(9)$ are associated to the unit cube points $(u,v) = (0,0)$, $(0,1)$, $(1,1)$ and $(1,0)$, respectively. The edge between corner $(3)$ and $(6)$ (i.e. the one with $v=1$) is foreground, the edge between $(1)$ and $(9)$ is background. Thus, large values of $v$ are drawn on top of small values of $v$. If $v$ is constant, large values of $u$ are drawn on top of small values of $u$. Thus, reordering the patch vertices (choosing a different first vertex and/or reversing the sequence) allows to get different foreground/background configurations\footnote{Internally, \PGFPlots\ employs such mechanisms to map the higher order isoparametric patch types to Coons patches, sorting according their corner's depth information.}. - The choice \declareandlabel{tensor bezier} is similar to |patch type=coons|: it allows to define a bezier patch. However, it allows more freedom: it has $16$ control points instead of the $12$ of a |coons| patch. The four additional control points are situated in the center of each patch. This |patch type| generates \texttt{.pdf} shadings of type~$7$ (whereas |coons| patches are shadings of type~$6$). It has been added for reasons of completeness, although it has not been tested properly. Please refer to the specification of the \texttt{.pdf} format for details\footnote{If someone is willing to test it and document it, feel free to email me!}. + The choice \declareandlabel{tensor bezier} is similar to |patch type=coons|: it allows to define a bezier patch. However, it allows more freedom: it has $16$ control points instead of the $12$ of a |coons| patch. The four additional control points are situated in the center of each patch. This |patch type| generates \texttt{.pdf} shadings of type~$7$ (whereas |coons| patches are shadings of type~$6$). It has been added for reasons of completeness, although it has not been tested properly. Please refer to the specification of the \texttt{.pdf} format for details\footnote{If someone is willing to test it and document it, feel free to email me!}. The choice |tensor bezier| is actually \emph{the same} as |patch type=bicubic| -- except that |bicubic| automatically respects the view depth (foreground/background) and is given in a different by means of function evaluations rather than control points. The choice \declareandlabel{polygon} expects polygons with a fixed number of vertices. This |patch type| requires the number of vertices as argument: @@ -287,7 +472,6 @@ table[row sep=\\] { The |patch type=polygon| supports \emph{neither} triangulation \emph{nor} shading \emph{nor} refinement. The order of appearance of the input points is supposed to be the order in which the line--to operations of the resulting path are generated. -\end{pgfplotskey} @@ -323,7 +507,7 @@ table[row sep=\\] { The refined patches reproduce the geometry's shape exactly. In addition, they improve color interpolation. Note that its purpose is just visualization, therefor hanging nodes are allowed (and will be generated by |patch refine| for most |patch type|s). - Patch refinement is implemented for all supported patches except for |patch type=coons|, |tensor bezier|, and |polygon|. + Patch refinement is implemented for all supported patches except for |patch type=coons|, |tensor bezier|, |bicubic| (might follow eventually) and |polygon|. \end{pgfplotskey} \begin{pgfplotskey}{patch to triangles=\mchoice{true,false} (initially false)} |