summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex430
1 files changed, 356 insertions, 74 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
index 7bd15bf2a25..a2cf31dec0e 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex
@@ -9,8 +9,8 @@ This list is copied from~\cite[section~29]{tikz}:
\begingroup
\newenvironment{longdescription}[0]{%
\begin{list}{}{%
- \leftmargin=4.3cm
- \setlength{\labelwidth}{4.3cm}%
+ \leftmargin=4.7cm
+ \setlength{\labelwidth}{4.7cm}%
\renewcommand{\makelabel}[1]{\hfill\textbf{\texttt{##1}}}%
}%
}{%
@@ -46,6 +46,7 @@ And with |\usetikzlibrary{plotmarks}|:
\item[mark=o] \showit{mark=o}
\item[mark=asterisk] \showit{mark=asterisk}
\item[mark=star] \showit{mark=star}
+ \item[mark=10-pointed star] \showit{mark=10-pointed star}
\item[mark=oplus] \showit{mark=oplus}
\item[mark=oplus*] \showit{mark=oplus*}
\item[mark=otimes] \showit{mark=otimes}
@@ -56,6 +57,18 @@ And with |\usetikzlibrary{plotmarks}|:
\item[mark=triangle*] \showit{mark=triangle*}
\item[mark=diamond] \showit{mark=diamond}
\item[mark=diamond*] \showit{mark=diamond*}
+ \item[mark=halfdiamond*] \showit{mark=halfdiamond*}
+ \item[mark=halfsquare*] \showit{mark=halfsquare*}
+ \item[mark=halfsquare right*] \showit{mark=halfsquare right*}
+ \item[mark=halfsquare left*] \showit{mark=halfsquare left*}
+ \item[mark=Mercedes star] \showit{mark=Mercedes star}
+ \item[mark=Mercedes star flipped] \showit{mark=Mercedes star flipped}
+ \item[mark=halfcircle] \showit{mark=halfcircle}
+
+ One half is filled with white (more precisely, with |mark color|).
+ \item[mark=halfcircle*] \showit{mark=halfcircle*}
+
+ One half is filled with white (more precisely, with |mark color|) and the other half is filled with the actual |fill| color.
\item[mark=pentagon] \showit{mark=pentagon}
\item[mark=pentagon*] \showit{mark=pentagon*}
\item[mark=text] \showit{mark=text,every mark/.append style={scale=0.5}}
@@ -63,7 +76,7 @@ And with |\usetikzlibrary{plotmarks}|:
This marker is special as it can be configured freely. The character (or even text) used is configured by a set of variables, see below.
\item[mark=cube] \showitpgfplots{mark=cube}
- This marker is only available inside of a \PGFPlots\ axis, it draws a cube with axis parallel faces. Its sizes can be configured separately, see below.
+ This marker is only available inside of a \PGFPlots\ axis, it draws a cube with axis parallel faces. Its dimensions can be configured separately, see below.
\item[mark=cube*] \showitpgfplots{mark=cube*}
\item[User defined] It is possible to define new markers with |\pgfdeclareplotmark|, see below.
@@ -78,10 +91,11 @@ All these options have been drawn with the additional options
}
]
\end{codeexample}
-Please see section~\ref{sec:colors} for how to change draw- and fill colors.
+Please see Section~\ref{sec:colors} for how to change |draw| and |fill| colors.
+Note that each of the provided marks can be rotated freely by means of |mark options={rotate=90}| or |every mark/.append style={rotate=90}|.
\begin{key}{/tikz/mark size=\marg{dimension}}
- This \Tikz\ option allows to set marker sizes to \marg{dimension}. For circular markers, \marg{dimension} is the radius, for other plot marks it is about half the width and height.
+ This \Tikz\ option allows to set marker sizes to \meta{dimension}. For circular markers, \meta{dimension} is the radius, for other plot marks it is about half the width and height.
\end{key}
\begin{pgfplotsxykey}{cube/size \x=\marg{dimension} (initially |\textbackslash pgfplotmarksize|)}
@@ -107,6 +121,24 @@ Please see section~\ref{sec:colors} for how to change draw- and fill colors.
\end{axis}
\end{tikzpicture}
\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[y=2cm]
+ \addplot+[
+ mark=halfcircle*,
+ every mark/.append style={rotate=90}]
+ coordinates
+ {(-2,0) (-1,1) (0,0) (1,1) (2,0)};
+
+ \addplot+[
+ mark=halfcircle*,
+ every mark/.append style={rotate=180}]
+ coordinates
+ {(-2,-0.1) (-1,0.9) (0,-0.1) (1,0.9) (2,-0.1)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
\end{key}
\begin{stylekey}{/pgfplots/no markers}
@@ -115,6 +147,35 @@ Please see section~\ref{sec:colors} for how to change draw- and fill colors.
If this style is provided as argument to a complete axis, it is appended to |every axis plot post| such that it disables markers even for |cycle list|s which contain markers.
\end{stylekey}
+\begin{key}{/tikz/mark repeat=\marg{integer} (initially empty)}
+ Allows to draw only each $n$th |mark| where $n$ is provided as \meta{integer}.
+\end{key}
+\begin{key}{/pgf/mark color=\marg{color} (initially empty)}
+ Defines the \emph{additional} fill color for the |halfcircle|, |halfcircle*|, |halfdiamond*| and |halfsquare*| markers. An empty value uses |white| (which is the initial configuration). The value |none| disables filling for this part.
+
+ These markers have two distinct fill colors, one is determined by |fill| as for any other marker and the other one is |mark color|.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[y=2cm]
+ \addplot[
+ blue,mark color=blue!50!white,
+ mark=halfcircle*]
+ coordinates
+ {(-2,0) (-1,1) (0,0) (1,1) (2,0)};
+
+ \addplot[
+ red,mark color=red!50!white,
+ mark=halfsquare*]
+ coordinates
+ {(-2,-0.1) (-1,0.9) (0,-0.1) (1,0.9) (2,-0.1)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ Note that this key requires \PGF\ 2.10 or later.
+\end{key}
+
+
\begin{key}{/tikz/mark options=\marg{options}}
Resets |every mark| to \marg{options}.
\end{key}
@@ -127,14 +188,14 @@ Please see section~\ref{sec:colors} for how to change draw- and fill colors.
With |/pgf/text mark=A|: \pgfkeys{/pgf/text mark=A}\showit{mark=text,every mark/.append style={scale=0.5}}
- There is no limitation about the number of characters or whatever. In fact, any \TeX\ material can be inserted as \marg{text}, including images.
+ There is no limitation about the number of characters or whatever. In fact, any \TeX\ material can be inserted as \meta{text}, including images.
\end{key}
\begin{key}{/pgf/text mark style=\marg{options for \texttt{mark=text}}}
Defines a set of options which control the appearance of |mark=text|.
- If |/pgf/text mark as node=false| (the default), \marg{options} is provided as argument to |\pgftext| -- which provides only some basic keys like |left|, |right|, |top|, |bottom|, |base| and |rotate|.
+ If |/pgf/text mark as node=false| (the default), \meta{options} is provided as argument to |\pgftext| -- which provides only some basic keys like |left|, |right|, |top|, |bottom|, |base| and |rotate|.
- If |/pgf/text mark as node=true|, \marg{options} is provided as argument to |\node|. This means you can provide a very powerful set of options including |anchor|, |scale|, |fill|, |draw|, |rounded corners| etc.
+ If |/pgf/text mark as node=true|, \meta{options} is provided as argument to |\node|. This means you can provide a very powerful set of options including |anchor|, |scale|, |fill|, |draw|, |rounded corners| etc.
\end{key}
\begin{key}{/pgf/text mark as node=\mchoice{true,false} (initially false)}
Configures how |mark=text| will be drawn: either as |\node| or as |\pgftext|.
@@ -143,7 +204,7 @@ Please see section~\ref{sec:colors} for how to change draw- and fill colors.
\end{key}
\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}}
- Defines a new marker named \marg{plot mark name}. Whenever it is used, \marg{code} will be invoked. It is suppose to contain (preferrable \PGF\ basic level) drawing commands. During \marg{code}, the coordinate system's origin denotes the coordinate where the marker shall be placed.
+ Defines a new marker named \meta{plot mark name}. Whenever it is used, \meta{code} will be invoked. It is supposed to contain (preferrable \PGF\ basic level) drawing commands. During \meta{code}, the coordinate system's origin denotes the coordinate where the marker shall be placed.
Please refer to~\cite{tikz} section ``Mark Plot Handler'' for more detailed information.
\end{command}
@@ -207,6 +268,32 @@ The following line styles are predefined in \Tikz.
\begin{stylekey}{/tikz/loosely dashed}
\showit{style=loosely dashed}
\end{stylekey}
+
+
+\begin{stylekey}{/tikz/dashdotted}
+ \showit{style=dashdotted}
+\end{stylekey}
+
+\begin{stylekey}{/tikz/densely dashdotted}
+ \showit{style=densely dashdotted}
+\end{stylekey}
+
+\begin{stylekey}{/tikz/loosely dashdotted}
+ \showit{style=loosely dashdotted}
+\end{stylekey}
+
+
+\begin{stylekey}{/tikz/dashdotdotted}
+ \showit{style=dashdotdotted}
+\end{stylekey}
+
+\begin{stylekey}{/tikz/densely dashdotdotted}
+ \showit{style=densely dashdotdotted}
+\end{stylekey}
+
+\begin{stylekey}{/tikz/loosely dashdotdotted}
+ \showit{style=loosely dashdotdotted}
+\end{stylekey}
\noindent since these styles apply to markers as well, you may want to consider using
\begin{codeexample}[code only]
\pgfplotsset{
@@ -218,6 +305,45 @@ The following line styles are predefined in \Tikz.
Besides linestyles, \PGF\ also offers (a lot of) arrow heads. Please refer to~\cite{tikz} for details.
\endgroup
+\subsubsection{Edges and Their Parameters}
+When \PGFPlots\ connects points, it relies on \PGF\ drawing parameters to create proper edges (and it only changes them in the |every patch| style).
+
+It might occasionally be necessary to change these parameters:
+
+\begin{keylist}{%
+ /tikz/line cap=\mchoice{round,rect,butt} (initially butt),%
+ /tikz/line join=\mchoice{round,bevel,miter} (initially miter),%
+ /tikz/miter limit=\meta{factor} (initially 10)}%
+
+ These keys control how lines are joined at edges. Their description is beyond the scope of this manual, so interested readers should consult~\cite{tikz}.
+
+ Here is just an example illustrating why it might be of interest to study these parameters:
+% \usetikzlibrary{spy}
+\begin{codeexample}[]
+% requires \usetikzlibrary{spy}
+\begin{tikzpicture}[spy using outlines=
+ {circle, magnification=6, connect spies}]
+\begin{axis}[no markers,grid=major,
+ every axis plot post/.append style={thick}]
+\addplot coordinates
+ {(0, 0.0) (0, 0.9) (1, 0.9) (2, 1) (3, 0.9) (80, 0)};
+\addplot +[line join=round] coordinates
+ {(0, 0.0) (0, 0.9) (2, 0.9) (3, 1) (4, 0.9) (80, 0)};
+\addplot +[line join=bevel] coordinates
+ {(0, 0.0) (0, 0.9) (3, 0.9) (4, 1) (5, 0.9) (80, 0)};
+\addplot +[miter limit=5] coordinates
+ {(0, 0.0) (0, 0.9) (4, 0.9) (5, 1) (6, 0.9) (80, 0)};
+
+ \coordinate (spypoint) at (axis cs:3,1);
+ \coordinate (magnifyglass) at (axis cs:60,0.7);
+\end{axis}
+
+\spy [blue, size=2.5cm] on (spypoint)
+ in node[fill=white] at (magnifyglass);
+\end{tikzpicture}
+\end{codeexample}
+\end{keylist}
+
\subsubsection{Font Size and Line Width}
Often, one wants to change line width and font sizes for plots. This can be done using the following options of \Tikz.
@@ -236,7 +362,7 @@ Often, one wants to change line width and font sizes for plots. This can be done
}
\end{codeexample}
- See also the predefined styles |normalsize|, |small| and |footnotesize| in section~\ref{sec:scaling:styles}.
+ See also the predefined styles |normalsize|, |small| and |footnotesize| in Section~\ref{sec:scaling:styles}.
\end{key}
\begin{key}{/tikz/line width=\marg{dimension} (initially 0.4pt)}
@@ -269,7 +395,7 @@ Often, one wants to change line width and font sizes for plots. This can be done
These \Tikz\ styles provide different predefined line widths.
\end{keylist}
-This example shows the same plots as on page~\pageref{page:plotcoords:src} (using |\plotcoords| as place holder for the commands on page~\pageref{page:plotcoords:src}), with different line width and font size.
+This example shows the same plots as on page~\pageref{page:plotcoords:src} (using |\plotcoords| as place holder for the commands on page~\pageref{page:plotcoords:src}), with different line widths and font sizes.
\begin{codeexample}[]
\pgfplotsset{every axis/.append style={
font=\large,
@@ -356,13 +482,19 @@ Besides predefined colors, it is possible to \emph{mix} two (or more) colors. Fo
A different type of color mixing is supported, which allows to take $100\%$ of \emph{each} component. For example, \showcolorandname{rgb,2:red,1;green,1} will add $1/2$ part \showcolorandname{red} and $1/2$ part \showcolorandname{green} and we reproduced the example from above. Using the denominator~$1$ instead of~$2$ leads to \showcolorandname{rgb,1:red,1;green,1} which uses $1$ part \showcolorandname{red} and $1$ part \showcolorandname{green}. Many programs allow to select pieces between $0,\dotsc,255$, so a denominator of $255$ is useful. Consequently, \showcolorandname{rgb,255:red,231;green,84;blue,121} uses $231/255$ red, $84/255$ green and $121/255$. This corresponds to the standard RGB color $(231,84,121)$. Other examples are \showcolorandname{rgb,255:red,32;green,127;blue,43}, \showcolorandname{rgb,255:red,178;green,127;blue,43}, \showcolorandname{rgb,255:red,169;green,178;blue,43}.
-It is also possible to use RGB values, the HSV color model or the HTML color syntax directly. However, this requires some more programming. I suppose this is the fastest (and probably the most uncomfortable) method to use colors. For example,
+It is also possible to use RGB values, the HSV color model, the CMY (or CMYK) models, or the HTML color syntax directly. However, this requires some more programming. I suppose this is the fastest (and probably the most uncomfortable) method to use colors. For example,
\begin{codeexample}[]
\definecolor{color1}{rgb}{1,1,0}
\tikz \fill[color1]
(0,0) rectangle (1em,0.6em);
\end{codeexample}
-\noindent creates the color with $100\%$ red, $100\%$ green and $0\%$ blue;
+\noindent creates the color with $100\%$ \showcolorandname{red}, $100\%$ \showcolorandname{green} and $0\%$ \showcolorandname{blue};
+\begin{codeexample}[]
+\definecolor{color1}{cmyk}{0.6,0.9,0.5,0.1}
+\tikz \fill[color1]
+ (0,0) rectangle (1em,0.6em);
+\end{codeexample}
+\noindent creates the color with $60\%$ \showcolorandname{cyan}, $90\%$ \showcolorandname{magenta}, $50\%$ \showcolorandname{yellow} and $10\%$ \showcolorandname{black};
\begin{codeexample}[]
\definecolor{color1}{HTML}{D0B22B}
@@ -378,7 +510,7 @@ The |xcolor| package provides even more methods to combine colors, among them th
/tikz/color=\marg{a color},
/tikz/draw=\marg{stroke color},
/tikz/fill=\marg{fill color}}
- These keys are (generally) used to set colors. Use |color| to set the color for both, drawing and filling. Instead of |color=|\marg{color name} you can simply write \marg{color name}. The |draw| and |fill| keys only set colors for stroking and filling, respectively.
+ These keys are (generally) used to set colors. Use |color| to set the color for both drawing and filling. Instead of |color=|\marg{color name} you can simply write \meta{color name}. The |draw| and |fill| keys only set colors for stroking and filling, respectively.
Use |draw=none| to disable drawing and |fill=none| to disable filling\footnote{Up to now, plot marks always have a stroke color (some also have a fill color). This restriction may be lifted in upcoming versions.}.% This does also work for markers.
%--------------------------------------------------
@@ -399,23 +531,23 @@ The |xcolor| package provides even more methods to combine colors, among them th
\subsubsection{Color Maps}
\label{pgfplots:colormap}
\begin{pgfplotskey}{colormap name=\marg{color map name} (initially hot)}
- Changes the current color map to the already defined map named \marg{color map name}. The predefined color map is
+ Changes the current color map to the already defined map named \meta{color map name}. The predefined color map is
\begin{tabular}{>{\ttfamily}ll}
hot & \pgfplotsshowcolormap{hot}\\
\end{tabular}
- Further color maps are described below.
+ The definition can be found in the documentation for |colormap/hot|. This, and further color maps, are described below.
- Colormaps can be used, for example, in scatter plots (see section~\ref{pgfplots:scatter}).
+ Colormaps can be used, for example, in scatter plots (see Section~\ref{pgfplots:scatter}).
You can use |colormap| to create new color maps (see below).
\end{pgfplotskey}
\begin{pgfplotskey}{colormap=\marg{name}\marg{color specification}}
- Defines a new colormap named \marg{name} according to \marg{color specification} and activates it using |colormap name=|\marg{name}.
+ Defines a new colormap named \meta{name} according to \meta{color specification} and activates it using |colormap name=|\marg{name}.
- The \marg{color specification} is a sequence of positions and associated colors where linear interpolation is applied in-between. The syntax is very similar as the one used for \PGF\ shadings described in~\cite[VIII -- Shadings]{tikz}: it is a semicolon--separated series of
+ The \meta{color specification} is a sequence of positions and associated colors where linear interpolation is applied in-between. The syntax is very similar as the one used for \PGF\ shadings described in~\cite[VIII -- Shadings]{tikz}: it is a semicolon--separated series of
\meta{color type}|(|\meta{offset}|)=(|\meta{color value}|); |:
@@ -425,7 +557,7 @@ rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb255(2cm)=(0,0,255); gray(3cm)=(0.3); col
\end{codeexample}
\pgfplotsshowcolormapexample{rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb255(2cm)=(0,0,255); gray(3cm)=(0.3); color(4cm)=(green)}
- If the distance between successive colors is the same anyway, one can skip the \meta{offset}. The `|;|' separators are not necessary as well:
+ If the distance between successive colors is the same, the \meta{offset} can be omitted. The `|;|' separators are not necessary either:
\begin{codeexample}[code only]
% (simplified) possibility 2: skip `;' and length arguments:
@@ -447,7 +579,19 @@ rgb=(1,0,0) rgb=(0,1,0) rgb255=(0,0,255) gray=(0.3) color=(green)
\noindent The single colors can be separated by semicolons `|;|'. The (optional) length describes how much of the bar is occupied by the interval, it is interpreted relative to the complete length. If the length argument is missing, it is taken to be the last specified length plus the last length difference (the first color defaults to |1cm| in this case).
-Each entry has the form \meta{color model}|(|\meta{length}|)=(|\meta{arguments}|)| where the \meta{length} argument is optional as discussed. The example above means that the left end of the color map shall have RGB components $1,0,0$, indicating $100\%$ red and $0\%$ green and blue. The next entity starts at |1cm| and describes a color with $100\%$ green. The |rgb255| also expects three RGB components, but in the range $[0,255]$. Finally, |gray| specifies a color in parenthesis with the same value for each, R G and B and |color| accesses predefined colors.
+\paragraph{Summary of the expected input format:}
+Each entry in \meta{color specification} has the form \meta{color model}|(|\meta{length}|)=(|\meta{arguments}|)|. Here, the \meta{length} argument is optional as discussed above. The entries can be separated by semicolons `|;|' or by white spaces. The leftmost entry \emph{must} have \meta{length}|=0pt|. As discussed, all entries will be placed on a uniform grid, i.e.\ the distance between adjacent \meta{length} arguments has to be the same (see the previous paragraph for automatic generation of intermediate points).
+The complete length of a color map is irrelevant: it will be mapped linearly to an internal range anyway (for efficient interpolation). The only requirement is that the left end must be at |0|.
+
+Available choices for \meta{color model} are
+\begin{description}
+\item[rgb] which expects \meta{arguments} of the form |(|\meta{red}|,|\meta{green}|,|\meta{blue}|)| where each component is in the interval $[0,1]$,
+\item[rgb255] which is similar to |rgb| except that each component is expected in the interval |[0,255]|,
+\item[gray] in which case \meta{arguments} is a single number in the interval $[0,1]$,
+\item[color] in which case \meta{arguments} contains a predefined (named) color like `|red|' or a color expression like `|red!50|',
+\item[cmyk] which expects \meta{arguments} of the form |(|\meta{cyan}|,|\meta{magenta}|,|\meta{yellow}|,|\meta{black}|)| where each component is in the interval $[0,1]$, and
+\item[cmyk255] which is the same as |cmyk| but expects components in the interval $[0,255]$.
+\end{description}
\begin{codeexample}[]
\begin{tikzpicture}
@@ -459,7 +603,19 @@ Each entry has the form \meta{color model}|(|\meta{length}|)=(|\meta{arguments}|
\end{axis}
\end{tikzpicture}
\end{codeexample}
-The complete length of a color map is irrelevant: it will be mapped linearly to an internal range anyway (for efficient interpolation). The only requirement is that the left end must be at |0|.
+
+\paragraph{The color space of a colormap.} There are two supported color spaces for a |colormap|: the RGB color space and the CMYK color space. Each access into a |colormap| requires linear interpolation which is performed in its color space. Color spaces make a difference: colors in different color spaces may be represented differently, depending on the output device. Many printers use CMYK for color printing, so providing CMYK colors might improve the printing quality on a color printer. The RGB color space is often used for display devices. The predefined |colormap|s in \PGFPlots\ all use RGB.
+
+Whenever a new |colormap| is created, \PGFPlots\ determines an associated color space. Then, each color in this specific |colormap| will be represented in its associated color space (converting colors automatically if necessary). Furthermore, every access into the |colormap| will be performed in its associated color space and every returned |mapped color| will be represented with respect to this color space. Furthermore, every shading generated by |shader=interp| will be represented with respect to the |colormap|'s associated color space.
+
+The color space is chosen as follows: in case |colormap default colorspace=auto| (the initial configuration), the color space depends on the \emph{first} encountered color in \meta{color specification}. For |rgb| or |gray| or |color|, the associated color space will be RGB (as it was in all earlier versions of \PGFPlots). For |cmyk|, the associated color space will be CMYK. If |colormap default colorspace| is either |rgb| or |cmyk|, this specific color space is used and every color is converted automatically.
+\begin{pgfplotskey}{colormap default colorspace=\mchoice{auto,rgb,cmyk} (initially auto)}
+ Allows to set the color space of every \emph{newly created} |colormap|. The choices are explained in the previous paragraph.
+
+ It is (not yet) possible to change the color space of an existing |colormap|; re-create it if conversion is required.
+
+ The macro \declareandlabel{\pgfplotscolormapgetcolorspace}\marg{name} defines |\pgfplotsretval| to contain the color space of an existing |colormap name|, if you are in doubt.
+\end{pgfplotskey}
Available color maps are shown below.
@@ -467,20 +623,68 @@ Available color maps are shown below.
\begin{stylekey}{/pgfplots/colormap/hot}
A style which installs the colormap
-
- |{color(0cm)=(blue); color(1cm)=(yellow); color(2cm)=(orange); color(3cm)=(red)}|
+\begin{codeexample}[code only]
+\pgfplotsset{
+ colormap={hot}{color(0cm)=(blue); color(1cm)=(yellow); color(2cm)=(orange); color(3cm)=(red)}
+}
+\end{codeexample}
\pgfplotsshowcolormap{hot}
This is the preconfigured color map.
\end{stylekey}
-\begin{stylekey}{/pgfplots/colormap/bluered}
- A style which installs the colormap
+\begin{stylekey}{/pgfplots/colormap/hot2}
+ A style which is equivalent to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ /pgfplots/colormap={hot2}{[1cm]rgb255(0cm)=(0,0,0) rgb255(3cm)=(255,0,0)
+ rgb255(6cm)=(255,255,0) rgb255(8cm)=(255,255,255)}
+}
+\end{codeexample}
+
+ \pgfplotsshowcolormap{hot2}
+
+ Note that this particular choice ships directly with \PGFPlots, you do not need to load the |colormaps| library for this value.
+
+ \matlabcolormaptext
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colormap/jet}
+ A style which is equivalent to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ /pgfplots/colormap={jet}{rgb255(0cm)=(0,0,128) rgb255(1cm)=(0,0,255)
+ rgb255(3cm)=(0,255,255) rgb255(5cm)=(255,255,0) rgb255(7cm)=(255,0,0) rgb255(8cm)=(128,0,0)}
+}
+\end{codeexample}
- \{|rgb255(0cm)=(0,0,180); rgb255(1cm)=(0,255,255); rgb255(2cm)=(100,255,0); |
+ \pgfplotsshowcolormap{jet}
- |rgb255(3cm)=(255,255,0); rgb255(4cm)=(255,0,0); rgb255(5cm)=(128,0,0)|\},
+ \matlabcolormaptext
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colormap/blackwhite}
+ A style which is equivalent to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ colormap={blackwhite}{gray(0cm)=(0); gray(1cm)=(1)}
+}
+\end{codeexample}
+
+ \pgfplotsshowcolormap{blackwhite}
+\end{stylekey}
+
+
+\begin{stylekey}{/pgfplots/colormap/bluered}
+ A style which is equivalent to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ colormap={bluered}{
+ rgb255(0cm)=(0,0,180); rgb255(1cm)=(0,255,255); rgb255(2cm)=(100,255,0);
+ rgb255(3cm)=(255,255,0); rgb255(4cm)=(255,0,0); rgb255(5cm)=(128,0,0)}
+}
+\end{codeexample}
\pgfplotsshowcolormap{bluered}
@@ -499,45 +703,49 @@ Available color maps are shown below.
\end{stylekey}
\begin{stylekey}{/pgfplots/colormap/cool}
- A style which installs the colormap
-
- |{rgb255(0cm)=(255,255,255); rgb255(1cm)=(0,128,255); rgb255(2cm)=(255,0,255)}|
+ A style which is equivalent to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ colormap={cool}{rgb255(0cm)=(255,255,255); rgb255(1cm)=(0,128,255); rgb255(2cm)=(255,0,255)}
+}
+\end{codeexample}
\pgfplotsshowcolormap{cool}
\end{stylekey}
\begin{stylekey}{/pgfplots/colormap/greenyellow}
- A style which installs the colormap
-
- |{rgb255(0cm)=(0,128,0); rgb255(1cm)=(255,255,0)}|
+ A style which is equivalent to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ colormap={greenyellow}{rgb255(0cm)=(0,128,0); rgb255(1cm)=(255,255,0)}
+}
+\end{codeexample}
\pgfplotsshowcolormap{greenyellow}
\end{stylekey}
\begin{stylekey}{/pgfplots/colormap/redyellow}
- A style which installs the colormap
-
- |{rgb255(0cm)=(255,0,0); rgb255(1cm)=(255,255,0)}|
+ A style which is equivalent to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ colormap={redyellow}{rgb255(0cm)=(255,0,0); rgb255(1cm)=(255,255,0)}
+}
+\end{codeexample}
\pgfplotsshowcolormap{redyellow}
\end{stylekey}
\begin{stylekey}{/pgfplots/colormap/violet}
- A style which installs the colormap
-
- |{rgb255=(25,25,122) color=(white) rgb255=(238,140,238)}|
+ A style which is equivalent to
+\begin{codeexample}[code only]
+\pgfplotsset{
+ colormap={violet}{rgb255=(25,25,122) color=(white) rgb255=(238,140,238)}
+}
+\end{codeexample}
\pgfplotsshowcolormap{violet}
\end{stylekey}
-\begin{stylekey}{/pgfplots/colormap/blackwhite}
- A style which installs the colormap
-
- |{gray(0cm)=(0); gray(1cm)=(1)}|
-
- \pgfplotsshowcolormap{blackwhite}
-\end{stylekey}
-
\begin{command}{\pgfplotscolormaptoshadingspec\marg{colormap name}\marg{right end size}\marg{\textbackslash macro}}
A command which converts a colormap into a \PGF\ shading's color specification. It can be used in commands like |\pgfdeclare*shading| (see the \PGF\ manual~\cite{tikz} for details).
@@ -552,13 +760,18 @@ Available color maps are shown below.
\pgfuseshading{tempshading}%
\end{codeexample}
The usage of the result \meta{\textbackslash macro} is a little bit low--level.
+
+ \paragraph{Attention:} \PGF\ shadings are always represented with respect to the RGB color space. Consequently, even CMYK \meta{colormap name}s will result in an RGB shading specification when using this method\footnote{In case \PGF\ should someday support CMYK shadings and you still see this remark, you can define \texttt{\textbackslash def\textbackslash pgfplotscolormaptoshadingspectorgb\{0\}}.}.
\end{command}
+
+Note that there \emph{more available choices} in the |colormaps| library which needs to be loaded by means of |\usepgfplotslibrary{colormaps}|.
+
\subsubsection{Cycle Lists -- Options Controlling Line Styles}
\label{sec:cycle:list}%
\begin{pgfplotskeylist}{cycle list=\marg{list},cycle list name=\marg{\textbackslash macro}}
-Allows to specify a list of plot specifications which will be used for each \hbox{|\addplot|}-command without explicit plot specification. Thus, the currently active |cycle list| will be used if you write either |\addplot+|\oarg{keys}| ...;| or if you \emph{don't} use square brackets as in |\addplot|\oarg{explicit plot specification}| ...;|.
+Allows to specify a list of plot specifications which will be used for each \hbox{|\addplot|} command without explicit plot specification. Thus, the currently active |cycle list| will be used if you write either |\addplot+|\oarg{keys}| ...;| or if you \emph{don't} use square brackets as in |\addplot|\oarg{explicit plot specification}| ...;|.
The list element with index~$i$ will be chosen where~$i$ is the index of the current |\addplot| command (see also the |cycle list shift| key which allows to use $i+n$ instead). This indexing does also include plot commands which don't use the |cycle list|.
@@ -641,6 +854,56 @@ There are several possibilities to change the currently active |cycle list|:
\begin{axis}[
stack plots=y,stack dir=minus,
cycle list name=mark list]
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ The |mark list| always employs the current color, but it doesn't define one (the \verbpdfref{\addplot+} statement explicitly sets the current color to |blue|).
+
+ The |mark list| is especially useful in conjunction with |cycle multi list| which allows to combine it with other lists (for example |linestyles| or a list of colors).
+ \item \declareandlabel{mark list*} A list containing only markers. In contrast to |mark list|, all these markers are filled. They are defined as (from top to bottom)
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ stack plots=y,stack dir=minus,
+ cycle list name=mark list*]
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\addplot+[blue] coordinates {(0,1) (0.5,1) (1,1)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ Similar to |mark list|, the |mark list*| always employs the current color, but it doesn't define one (see above for the \verbpdfref{\addplot+}).
+
+ \item \declareandlabel{color list} (from top to bottom)
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ stack plots=y,stack dir=minus,
+ cycle list name=color list]
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
@@ -658,15 +921,14 @@ There are several possibilities to change the currently active |cycle list|:
\end{tikzpicture}
\end{codeexample}
- The |mark list| always employs the current color, but it doesn't define one.
-
+ The |cycle list name=color| choice also employs markers whereas |color list| uses \emph{only} colors.
- \item \declareandlabel{color list} (from top to bottom)
+ \item \declareandlabel{linestyles} (from top to bottom)
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
stack plots=y,stack dir=minus,
- cycle list name=color list]
+ cycle list name=linestyles]
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
@@ -683,15 +945,12 @@ There are several possibilities to change the currently active |cycle list|:
\end{axis}
\end{tikzpicture}
\end{codeexample}
-
- The |cycle list name=color| choice also employs markers whereas |color list| uses \emph{only} colors.
-
- \item \declareandlabel{linestyles} (from top to bottom)
+ \item \declareandlabel{linestyles*} contains more dotted line styles than |linestyles| (from top to bottom)
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
stack plots=y,stack dir=minus,
- cycle list name=linestyles]
+ cycle list name=linestyles*]
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
@@ -759,16 +1018,38 @@ The definitions of all predefined cycle lists follow (see the end of this paragr
\begin{codeexample}[code only]
% note that "." is the currently defined Tikz color.
\pgfplotscreateplotcyclelist{mark list}{%
- every mark/.append style={fill=.!80!black},mark=*\\%
- every mark/.append style={fill=.!80!black},mark=square*\\%
- every mark/.append style={fill=.!80!black},mark=triangle*\\%
- mark=star\\%
- every mark/.append style={fill=.!80!black},mark=diamond*\\%
- every mark/.append style={fill=.!80!black},mark=otimes*\\%
- mark=|\\%
- every mark/.append style={fill=.!80!black},mark=pentagon*\\%
- mark=text,text mark=p\\%
- mark=text,text mark=a\\%
+ every mark/.append style={solid,fill=.!80!black},mark=*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=square*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=triangle*\\%
+ every mark/.append style={solid},mark=star\\%
+ every mark/.append style={solid,fill=.!80!black},mark=diamond*\\%
+ every mark/.append style={solid,fill=.!80!black!40},mark=otimes*\\%
+ every mark/.append style={solid},mark=|\\%
+ every mark/.append style={solid,fill=.!80!black},mark=pentagon*\\%
+ every mark/.append style={solid},mark=text,text mark=p\\%
+ every mark/.append style={solid},mark=text,text mark=a\\%
+}
+\end{codeexample}
+\noindent This is not the complete truth: the actual implementation of |mark list| allows to customize the |fill| value:
+\begin{pgfplotskey}{mark list fill=\marg{color} (initially .!80!black)}
+ Allows to customize the fill color for the |mark list| and |mark list*|.
+
+ For example, if you have |black| as color, the alternative choice |mark list fill=.!50!white| will produce much better results.
+\end{pgfplotskey}
+\begin{codeexample}[code only]
+% note that "." is the currently defined Tikz color.
+\pgfplotscreateplotcyclelist{mark list*}{%
+ every mark/.append style={solid,fill=.!80!black},mark=*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=square*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=triangle*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=halfsquare*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=pentagon*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=halfcircle*\\%
+ every mark/.append style={solid,fill=.!80!black,rotate=180},mark=halfdiamond*\\%
+ every mark/.append style={solid,fill=.!80!black!40},mark=otimes*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=diamond*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=halfsquare right*\\%
+ every mark/.append style={solid,fill=.!80!black},mark=halfsquare left*\\%
}
\end{codeexample}
\begin{codeexample}[code only]
@@ -777,6 +1058,7 @@ The definitions of all predefined cycle lists follow (see the end of this paragr
\end{codeexample}
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{linestyles}{solid,dashed,dotted}
+\pgfplotscreateplotcyclelist{linestyles*}{solid,dashed,dotted,dashdotted,dashdotdotted}
\end{codeexample}
\item The second choice for cycle lists is to provide each entry directly as argument to |cycle list|,
@@ -798,7 +1080,7 @@ The definitions of all predefined cycle lists follow (see the end of this paragr
\end{codeexample}
(This example list requires |\usetikzlibrary{plotmarks}|).
- The input format is described below in more details.
+ The input format is described below in more detail.
\item The last method is to combine 1. and 2.: Define named cycle lists in the preamble and use them with `|cycle list name|':
\begin{command}{\pgfplotscreateplotcyclelist\marg{name}\marg{list}}%
@@ -817,7 +1099,7 @@ The definitions of all predefined cycle lists follow (see the end of this paragr
\end{codeexample}
\end{enumerate}
-\paragraph{The format of \marg{list}:} The argument \meta{list} is usually a comma separated list of lists of style keys like colors, line styles, marker types and marker styles. This ``comma list of comma lists'' structure requires to encapsulate the inner list using curly braces:
+\paragraph{The format of \meta{list}:} The argument \meta{list} is usually a comma separated list of lists of style keys like colors, line styles, marker types and marker styles. This ``comma list of comma lists'' structure requires to encapsulate the inner list using curly braces:
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{mylist}{%
{blue,mark=*},
@@ -950,7 +1232,7 @@ In this case, the \emph{last} entry also needs a terminating `|\\|', but one can
\end{pgfplotskey}
\begin{pgfplotskey}{cycle list shift=\marg{integer} (initially empty)}
- Allows to \emph{shift} the index into the |cycle list|. If \meta{integer} is $n$, the list element $i+n$ will be taken instead of the $i$'th one. Remember that $i$ is the index of the current |\addplot| command (starting with~$0$).
+ Allows to \emph{shift} the index into the |cycle list|. If \meta{integer} is $n$, the list element $i+n$ will be taken instead of the $i$th one. Remember that $i$ is the index of the current |\addplot| command (starting with~$0$).
Since a |cycle list| is queried \emph{immediately} when |\addplot| (or |\addplot+|) is called, you can adjust the |cycle list shift| for selected plots:
\begin{codeexample}[code only]
@@ -1031,7 +1313,7 @@ A further common idea is the use of color maps: if the point meta data is in the
\item[\declaretext{explicit}] This choice tells \PGFPlots\ to expect \emph{numerical} point meta data which is provided explicitly in the coordinate input streams. This data will be transformed linearly into the current color map as it has been motivated above.
- How point meta data is provided for |plot coordinates|, |plot table| and the other input methods is described in all detail in section~\ref{pgfplots:providing:input} -- but we provide small examples here to summarize the possibilities:
+ How point meta data is provided for |plot coordinates|, |plot table| and the other input methods is described in all detail in Section~\ref{pgfplots:providing:input} -- but we provide small examples here to summarize the possibilities:
\begin{codeexample}[code only]
% for 'coordinates':
% provide color data explicitly using [<data>]
@@ -1100,7 +1382,7 @@ A further common idea is the use of color maps: if the point meta data is in the
Currently, this choice can only be used for scatter plots.
- \item[\normalfont\declare{\meta{expression}}] This choice allows to compute point meta data using a mathematical expression. The \meta{expression} may depend on |x|, |y|, |z| which yield the current $x$, $y$ or $z$ coordinate, respectively. The coordinates are completely processed (transformations, logs) as mentioned above for the choice |x|. Furthermore, the \meta{expression} may depend on commands which are valid during |\addplot| like |\plotnum| or |\coordindex| (see section~\ref{pgfplots:misc} for details). Computations are performed using the floating point unit of \PGF, and all supported arithmetical operations can be used.
+ \item[\normalfont\declare{\meta{expression}}] This choice allows to compute point meta data using a mathematical expression. The \meta{expression} may depend on |x|, |y|, |z| which yield the current $x$, $y$ or $z$ coordinate, respectively. The coordinates are completely processed (transformations, logs) as mentioned above for the choice |x|. Furthermore, the \meta{expression} may depend on commands which are valid during |\addplot| like |\plotnum| or |\coordindex| (see Section~\ref{pgfplots:misc} for details). Computations are performed using the floating point unit of \PGF, and all supported arithmetical operations can be used.
In essence, the \meta{expression} may depend on everything which is known to all |\addplot| commands: the $x$, $y$ and (if any) $z$ coordinates. In addition, it may depend upon |rawx|, |rawy| or |rawz|. These three expressions yield the unprocessed $x$, $y$ or $z$ value as it has been found in the input stream (no logs, no user transformations)%
\footnote{%
@@ -1180,7 +1462,7 @@ A further common idea is the use of color maps: if the point meta data is in the
\end{pgfplotskeylist}
\begin{pgfplotskey}{colormap access=\mchoice{map,direct} (initially map)}
- This key configures how point meta data is used to determine colors from a color map. The initial configuration |map| performs the linear mapping operation explained above. The choice |direct| does not perform any transformation; it takes the point meta as integer indizes into the current color map.
+ This key configures how point meta data is used to determine colors from a color map. The initial configuration |map| performs the linear mapping operation explained above. The choice |direct| does not perform any transformation; it takes the point meta as integer indices into the current color map.
Consequently, there is no interpolation between colors in the color map, there will only be as many colors as the color map contains explicitly.