summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex
diff options
context:
space:
mode:
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.tex56
1 files changed, 53 insertions, 3 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 f226828055a..c78c71af974 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.patchplots.tex
@@ -5,7 +5,7 @@
\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} (initially default)}
+\begin{pgfplotskey}{patch type=\mchoice{default,rectangle,triangle,line,quadratic spline,cubic spline,\\bilinear,triangle quadr,biquadratic,coons,polygon,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:
@@ -207,7 +207,57 @@ coordinates {
\noindent The four cubic B\'ezier curves are \emph{equivalent} to \texttt{curveto} paths of \pgfname, i.e.\ \parg{corner 1}|.. controls|\parg{control point A}| and |\parg{control point B}| .. |\parg{corner 2} paths. The interpolated shading is bilinear. More precisely, a bilinear shading in the unit cube $[0,1]^2$ is initialised which is then mapped into the Coons patch such that the corners match. The color interpolation uses only the color data of the four corners, color values of intermediate control points are ignored for the shading (although their value will be respected for the upper and lower limit of color data). In contrast to the finite element patches, a Coons patch is inherently two--dimensional. While you can still use three--dimensional coordinates, \PGFPlots\ will draw the shading as you provide it, without checking for the depth information (as it does for the other |patch type|s). In other words: depending on the current |view| angle, the shading might fold over itself in unexpected ways.
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{polygon} expects polygons with a fixed number of vertices. This |patch type| requires the number of vertices as argument:
+ \begin{pgfplotskey}{vertex count=\meta{count}}
+ The number of vertices to be used for |patch type=polygon|. The number can be arbitrary. All input patches are expected to have this many vertices -- but it is acceptable if a patch uses the same vertex multiple times. This means that |patch type=polygon| accepts polygons with different numbers of vertices, but you need to apply some sort of ``manual padding''.
+
+ This parameter is (currently) mandatory.
+ \end{pgfplotskey}
+ A |patch| plot with |patch type=polygon| simply connects the $n$=|vertex count| vertices in their order of appearance and closes the resulting path:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[view/h=120,xlabel=$x$,ylabel=$y$]
+ \addplot3[
+ opacity=0.5,
+ table/row sep=\\,
+ patch,
+ patch type=polygon,
+ vertex count=5,
+ patch table with point meta={%
+ % pt1 pt2 pt3 pt4 pt5 cdata
+ 0 1 7 2 2 0\\
+ 1 6 5 5 5 1\\
+ 1 5 4 2 7 2\\
+ 2 4 3 3 3 3\\
+ }]
+ table {
+ x y z\\
+ 0 2 0\\%0
+ 2 2 0\\%1
+ 0 1 3\\%2
+ 0 0 3\\%3
+ 1 0 3\\%4
+ 2 0 2\\%5
+ 2 0 0\\%6
+ 1 1 2\\%7
+ };
+% replicate the vertex list to show \coordindex:
+\addplot3[only marks,nodes near coords=\coordindex]
+table[row sep=\\] {
+0 2 0\\ 2 2 0\\ 0 1 3\\ 0 0 3\\
+1 0 3\\ 2 0 2\\ 2 0 0\\ 1 1 2\\
+};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ \noindent The example above defines the |patch| by means of a connectivity table (|patch table with point meta|) and a vertex list (the normal input coordinates of the plot): there are~$8$ vertices and~$4$ polygons. Note that~$2$ of these polygons are triangles, one has $4$ corners and only of them actually has all~$5$ allocated corners. This effect can be achieved by replicating one of the corners. The connectivity table in our example defines a unique color for each polygon: $0$ for the first patch, $1$ for the second, $2$ for the third, and $3$ for the last. These numbers map into the current |colormap|.
+
+ 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}
@@ -243,7 +293,7 @@ coordinates {
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|.
+ Patch refinement is implemented for all supported patches except for |patch type=coons|, |tensor bezier|, and |polygon|.
\end{pgfplotskey}
\begin{pgfplotskey}{patch to triangles=\mchoice{true,false} (initially false)}
@@ -270,7 +320,7 @@ coordinates {
For one--dimensional |patch type|s like |quadratic spline|, |patch to triangles| results in approximation by means of |patch type=line| instead of |triangle|.
- The |patch to triangles| feature is implemented for all supported patches except for |patch type=coons|.
+ The |patch to triangles| feature is implemented for all supported patches except for |patch type=coons|, |tensor bezier|, and |polygon|.
\end{pgfplotskey}
\subsubsection{Peculiarities of Flat Shading and High Order Patches}