
\section{Markers, Linestyles, (Background-) Colors and Colormaps}
\label{sec:markers}%
The following options of \Tikz\ are available to plots.

\subsection{Markers}
This list is copied from~\cite[section~29]{tikz}:
\pgfmanualpdflabel{/tikz/mark}{}%
\begingroup
\newenvironment{longdescription}[0]{%
	\begin{list}{}{%
		\leftmargin=4.7cm
		\setlength{\labelwidth}{4.7cm}%
		\renewcommand{\makelabel}[1]{\hfill\textbf{\texttt{##1}}}%
	}%
}{%
	\end{list}%
}%
\def\showit#1{%
	\tikz\draw[%
		gray,
		thin,
		mark options={fill=yellow!80!black,draw=black,scale=2},
		x=0.8cm,y=0.3cm,
		#1]
	plot coordinates {(0,0) (1,1) (2,0) (3,1)};%
}%
\def\showitpgfplots#1{%
\begin{tikzpicture}[baseline]
	\begin{axis}[anchor=north,xticklabels=,yticklabels=,zticklabels=,width=5cm]
	\addplot3[gray, thin, mark options={scale=2,fill=yellow!80!black,draw=black},#1]
		plot coordinates {(0,0,0) (0.3,0.6,0.3) (2,0,0.1) (2.3,1,0.2)};
	\end{axis}
\end{tikzpicture}%
}%
\begin{longdescription}
	\item[mark=*] \showit{mark=*}
	\item[mark=x] \showit{mark=x}
	\item[mark=+] \showit{mark=+}
%	\item[mark=ball] \showit{mark=ball}
\end{longdescription}
And with |\usetikzlibrary{plotmarks}|:
\begin{longdescription}
	\item[mark=$-$] \showit{mark=-}
	\item[mark=$\vert$] \showit{mark=|}
	\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}
	\item[mark=otimes*] \showit{mark=otimes*}
	\item[mark=square] \showit{mark=square}
	\item[mark=square*] \showit{mark=square*}
	\item[mark=triangle] \showit{mark=triangle}
	\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=ball] \showit{mark=ball,mark options={ball color=yellow!80!black,scale=2}}

		This marker is special and can easily generate big output files if there are lots of them. It is also special in that it needs |ball color| to be set (in our case, it is |ball color=yellow!80!black|.

	\item[mark=text] \showit{mark=text,every mark/.append style={scale=0.5}} 

	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 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.
\end{longdescription}
All these options have been drawn with the additional options
\begin{codeexample}[code only]
\draw[
	gray,
	thin,
	mark options={%
		scale=2,fill=yellow!80!black,draw=black
	}
]
\end{codeexample}
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} (initially 2pt)}
	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|=2pt)}
	Sets the size for |mark=cube| separately for every axis.
\end{pgfplotsxykey}
\begin{key}{/tikz/every mark}
	This \Tikz\ style can be reconfigured to set marker appearance options like colors or transformations like scaling or rotation. \PGFPlots\ appends its |cycle list| options to this style.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[y=2cm]
	\addplot coordinates 
		{(-2,0) (-1,1) (0,0) (1,1) (2,0)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\tikzset{every mark/.append style={scale=2}}
\begin{tikzpicture}
\begin{axis}[y=2cm]
	\addplot coordinates 
		{(-2,0) (-1,1) (0,0) (1,1) (2,0)};
\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}

	Note that |every mark| is kind of static in the sense that it is evaluated once only. If you need individually colored markes as part of a |scatter| plot, you will need to resort to |scatter/use mapped color|.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[y=2cm]
  \addplot+[
	mark=ball,
	mark size=4pt,
	scatter,% enable scatter
	scatter src=rand,% the "color data"
	% configure individual appearances:
	scatter/use mapped color=
	  {ball color=mapped color}]
  coordinates 
	{(-2,0) (-1,1) (0,0) (1,1) (2,0)};

\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{key}

\begin{stylekey}{/pgfplots/no markers}
	A key which overrides any |mark| value set by |cycle list| of option lists after |\addplot|.

	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}{/tikz/mark phase=\marg{integer $p$} (initially 1)}
	This option allows to control which markers are drawn. It is primarily used together with the \Tikz\ option |mark repeat=|$r$: it 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}[]
\begin{tikzpicture}
	\begin{axis}[tiny]
	\addplot+[scatter] {sin(deg(x))};	
	\end{axis}
\end{tikzpicture}
\begin{tikzpicture}
	\begin{axis}[tiny]
	\addplot+[scatter,
	  mark repeat=3,mark phase=2]
	  {sin(deg(x))};	
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	Here, $p=1$ is the first point (the one with |\coordindex|$=0$).
\end{key}

\begin{key}{/tikz/mark indices=\marg{index list} (initially empty)}
	Allows to draw only the marker whose index numbers are in the argument list.
\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}


\begin{key}{/pgf/text mark=\marg{text} (initially p)}
	Changes the text shown by |mark=text|.

	With |/pgf/text mark=m|: \pgfkeys{/pgf/text mark=m}\showit{mark=text,every mark/.append style={scale=0.5}}

	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 \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), \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|, \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|.

	The first choice is highly flexible and possibly slow, the second is very fast and usually enough.
\end{key}

\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}}
	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}



\begin{stylekey}{/pgfplots/every axis plot post (initially {})}
The |every axis plot post| style can be used to overwrite parts (or all) of the drawing styles which are assigned for plots.
\begin{codeexample}[]
% Overwrite any cycle list:
\pgfplotsset{
  every axis plot post/.append style={
   mark=triangle,
   every mark/.append style={rotate=90}}}
\begin{tikzpicture}
\begin{axis}[y=2cm]
	\addplot coordinates 
		{(-2,0) (-1,1) (0,0) (1,1) (2,0)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{stylekey}

Markers paths are not subjected to clipping as other parts of the figure. Markers are either drawn completely or not at all.

\Tikz\ offers more options for marker fine tuning, please refer to~\cite{tikz} for details.

\subsection{Line Styles}
\def\showit#1{%
	\tikz\draw[%
		black,
		x=0.8cm,y=0.3cm,
		#1]
	plot coordinates {(0,0) (1,1) (2,0) (3,1)};%
}%
The following line styles are predefined in \Tikz.
\begin{stylekey}{/tikz/solid}
	 \showit{style=solid}
\end{stylekey}

\begin{stylekey}{/tikz/dotted}
	 \showit{style=dotted}
\end{stylekey}

\begin{stylekey}{/tikz/densely dotted}
	 \showit{style=densely dotted}
\end{stylekey}

\begin{stylekey}{/tikz/loosely dotted}
	 \showit{style=loosely dotted}
\end{stylekey}

\begin{stylekey}{/tikz/dashed}
	 \showit{style=dashed}
\end{stylekey}

\begin{stylekey}{/tikz/densely dashed}
	 \showit{style=densely dashed}
\end{stylekey}

\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{
	every mark/.append style={solid}
}
\end{codeexample}
\noindent in marker styles.

Besides linestyles, \PGF\ also offers (a lot of) arrow heads. Please refer to~\cite{tikz} for details.
\endgroup

\subsection{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 (3,1);
  \coordinate (magnifyglass) at (60,0.7);
\end{axis}

\spy [blue, size=2.5cm] on (spypoint)
   in node[fill=white] at (magnifyglass);
\end{tikzpicture}
\end{codeexample}
\end{keylist}


\subsection{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.

\begin{key}{/tikz/font=\marg{font name} (initially \textbackslash normalfont)}
	Sets the font which is to be used for text in nodes (like tick labels, legends or descriptions).

	A font can be any \LaTeX\ argument like |\footnotesize| or |\small\bfseries|\footnote{Con\TeX t and plain \TeX\ users need to provide other statements, of course.}.

	It may be useful to change fonts only for specific axis descriptions, for example using
\begin{codeexample}[code only]
\pgfplotsset{
	tick label style={font=\small},
	label style={font=\small},
	legend style={font=\footnotesize}
}
\end{codeexample}

	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)}
	Sets the line width. Please note that line widths for tick lines and grid lines are predefined, so it may be necessary to override the styles |every tick| and |every axis grid|.

	The |line width| key is changed quite often in \Tikz. You should use
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={line width=1pt}}
\end{codeexample}
	or
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={thick}}
\end{codeexample}
	to change the overall line width. To also adjust ticks and grid lines, one can use
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={
	line width=1pt,
	tick style={line width=0.6pt}}}
\end{codeexample}
	or styles like
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={
	thick,
	tick style={semithick}}}
\end{codeexample}
	The `|every axis plot|' style can be used to change line widths for plots only.
\end{key}

\begin{keylist}[/tikz]{thin,ultra thin,very thin,semithick,thick,very thick,ultra thick}
	These \Tikz\ styles provide different predefined line widths.
\end{keylist}

\begin{codeexample}[]
\pgfplotsset{every axis/.append style={
	font=\large,
	line width=1pt,
	tick style={line width=0.8pt}}}
\begin{tikzpicture}
\begin{loglogaxis}[
	legend style={at={(0.03,0.03)},
		anchor=south west},
	xlabel=\textsc{Dof},
	ylabel=$L_2$ Error
]
\addplot coordinates {
	(5,8.312e-02)    (17,2.547e-02)   (49,7.407e-03)
	(129,2.102e-03)  (321,5.874e-04)  (769,1.623e-04)
	(1793,4.442e-05) (4097,1.207e-05) (9217,3.261e-06)
};

\addplot coordinates{
	(7,8.472e-02)    (31,3.044e-02)   (111,1.022e-02)
	(351,3.303e-03)  (1023,1.039e-03) (2815,3.196e-04)
	(7423,9.658e-05) (18943,2.873e-05)
	(47103,8.437e-06)};

\addplot coordinates{
	(9,7.881e-02)     (49,3.243e-02)   (209,1.232e-02)
	(769,4.454e-03)   (2561,1.551e-03) 
	(7937,5.236e-04)  (23297,1.723e-04)
	(65537,5.545e-05) (178177,1.751e-05)};

\addplot coordinates{
	(11,6.887e-02)    (71,3.177e-02)   (351,1.341e-02)
	(1471,5.334e-03)  (5503,2.027e-03) 
	(18943,7.415e-04) (61183,2.628e-04)
	(187903,9.063e-05) (553983,3.053e-05)};

\addplot coordinates{
	(13,5.755e-02)    (97,2.925e-02)   (545,1.351e-02)
	(2561,5.842e-03)  (10625,2.397e-03)
	(40193,9.414e-04) (141569,3.564e-04)
	(471041,1.308e-04) (1496065,4.670e-05)};
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
The preceding example defines data which is used a couple of times throughout this manual; it is referenced by
\label{page:plotcoords:src}%
\declareandlabel{\plotcoords}.%

\begin{codeexample}[]
\pgfplotsset{every axis/.append style={
	font=\footnotesize,
	thin,
	tick style={ultra thin}}}
\begin{tikzpicture}
	\begin{loglogaxis}[
		xlabel=\textsc{Dof},
		ylabel=$L_2$ Error
	]
	% see above for this macro:
	\plotcoords
	\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
	\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}


\subsection{Colors}
\label{sec:colors}
{%
\def\showcolorandname#1{%
	\showcolor{#1}~\texttt{\pgfmanualpdflabel{#1}{#1}}%
}%
\def\showcolor#1{%
	\tikz \draw[black,fill={#1}] (0,0) rectangle (1em,0.6em);%
}%
\PGF\ uses the color support of |xcolor|. Therefore, the main reference for how to specify colors is the |xcolor| manual~\cite{xcolor}. The \PGF\ manual~\cite{tikz} is the reference for how to select colors for specific purposes like drawing, filling, shading, patterns etc.\ This section contains a short overview over the specification of colors in~\cite{xcolor} (which is not limited to \PGFPlots).

The package |xcolor| defines a set of predefined colors, namely 
\showcolorandname{red},
\showcolorandname{green},
\showcolorandname{blue},
\showcolorandname{cyan},
\showcolorandname{magenta},
\showcolorandname{yellow},
\showcolorandname{black},
\showcolorandname{gray},
\showcolorandname{white},
\showcolorandname{darkgray},
\showcolorandname{lightgray},
\showcolorandname{brown},
\showcolorandname{lime},
\showcolorandname{olive},
\showcolorandname{orange},
\showcolorandname{pink},
\showcolorandname{purple},
\showcolorandname{teal},
\showcolorandname{violet}.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[enlarge x limits=false]
	\addplot[red,samples=500] {sin(deg(x))};

	\addplot[orange,samples=7] {sin(deg(x))};

	\addplot[teal,const plot,
		samples=14] {sin(deg(x))};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

Besides predefined colors, it is possible to \emph{mix} two (or more) colors. For example, \showcolorandname{red!30!white} contains $30\%$ of \showcolorandname{red} and $70\%$ of \showcolorandname{white}. Consequently, one can build \showcolorandname{red!70!white} to get $70\%$ red and $30\%$ white or \showcolorandname{red!10!white} for $10\%$ red and $90\%$ white. This mixing can be done with any color, for example \showcolorandname{red!50!green}, \showcolorandname{blue!50!yellow} or \showcolorandname{green!60!black}.

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, 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\%$ \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}
\tikz \fill[color1] 
	(0,0) rectangle (1em,0.6em);
\end{codeexample}
\noindent creates the color with $208/255$ pieces red, $178/255$ pieces green and $43$ pieces blue, specified in standard HTML notation. Please refer to the |xcolor| manual~\cite{xcolor} for more details and color models.

The |xcolor| package provides even more methods to combine colors, among them the prefix `|-|' (minus) which changes the color into its complementary color (\showcolorandname{-black}, \showcolorandname{-white}, \showcolorandname{-red}) or color wheel calculations. Please refer to the |xcolor| manual~\cite{xcolor}.
}%

\begin{keylist}{
	/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 \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.
%--------------------------------------------------
% \ begin{codeexample}[]
% \begin{tikzpicture}
% 	\begin{axis}
% 	\addplot+[only marks,mark=square*,
% 		mark options={fill=red!50!white,draw=none}]
% 		{4*x^2 - 2*x +4 };
% 	\end{axis}
% \end{tikzpicture}
% \end{codeexample}
%-------------------------------------------------- 

	Since these keys belong to \Tikz, the complete documentation can be found in the \Tikz\ manual~\cite[Section ``Specifying a Color'']{tikz}.
\end{keylist}

\subsubsection{Color Spaces}

Since \PGFPlots\ relies on |xcolor|, all mechanisms of |xcolor| to define color spaces apply here as well.

One of the most useful approaches is global color space conversion: if you want a document which contains only colors in the |cmyk| color spaces, you can say

\begin{codeexample}[code only]
\usepackage[cmyk]{xcolor}
\usepackage{pgfplots}
\end{codeexample}
\noindent in order to convert all colors of the entire document (including all shaded) to |cmyk|.

The same can be achieved by means of the |xcolor| statement \declareandlabel{\selectcolormodel}.
\begin{codeexample}[code only]
\selectcolormodel{cmyk}
\end{codeexample}


\subsection{Color Maps}

A ``color map'' is a sequence of colors with smooth transitions between them. Color maps are often used to visualize ``color data'' in plots: in this case, a plot has the position coordinates $(x,y)$ and some additional scalar value (|point meta|) which can be used as ``color data''. The smallest encountered |point meta| is then mapped to the first color of a |colormap|, the largest encountered value of |point meta| is mapped to the last color of a |colormap|, and interpolation happens in-between.

\label{pgfplots:colormap}
\begin{pgfplotskey}{colormap name=\marg{color map name} (initially hot)}
	Changes the current color map to the already defined map named \meta{color map name}. The predefined color maps are

	\begin{tabular}{>{\ttfamily}ll}
	viridis & \pgfplotsshowcolormap{viridis}\\
	hot & \pgfplotsshowcolormap{hot}\\
	\end{tabular}

	The definition can be found in the documentation for |colormap/hot| and |colormap/viridis|, respectively. 
	These, and further color maps, are described below.

	Color maps can be used, for example, in |scatter| plots and |surf|ace plots.

	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 \meta{name} according to \meta{color specification} and activates it using |colormap name=|\marg{name}.
	
	A simple \meta{color specification} is just a sequence of color definitions of type

	\meta{color type}|=(|\meta{color value}|)|

	separated by either white spaces or semicolon or comma:

\begin{codeexample}[code only]
\pgfplotsset{colormap={CM}{rgb=(0,0,1) color=(black) rgb255=(238,140,238)}}
\end{codeexample}
\pgfplotsshowcolormapexample{rgb=(0,0,1) color=(black) rgb255=(238,140,238)}

	Here, the three input colors form the left end, middle point, and right end of the interval, respectively. A couple of \meta{color type}s are available, the \meta{color value} depends on the actual \meta{color type} which is shown below in all detail. Most |colormap| definitions use the simple form and merely list suitable color definitions.

	A more advanced \meta{color specification} is one which defines both colors and positions in order to define the place of each color. In this case, \PGFPlots\ offers the syntax

	\meta{color type}|(|\meta{offset}|)=(|\meta{color value}|)|:

\begin{codeexample}[code only]
\pgfplotsset{colormap={CM}{rgb(-500)=(0,0,1) color(0)=(black) rgb255(1500)=(238,140,238)}}
\end{codeexample}
\pgfplotsshowcolormapexample{rgb(-500)=(0,0,1) color(0)=(black) rgb255(1500)=(238,140,238)}
	
	This syntax allows to distribute colors over the interval using non-uniform distances. 
	
	\paragraph{Compatibility note}: \PGFPlots\ up to and including version $1.13$ offered just rudimentary support for non-uniform color maps. You need to write |compat=1.14| or higher in order to make use of non-uniform color maps.
	\index{Color maps!Non uniform, compatibility constraints}
	
	The positions can be arbitrary numbers\footnote{Note that \PGFPlots\ up to and including version $1.13$ only supported ranges $[0,16300]$.} (or dimensions), but each new color must come with a larger position than its preceding one. The position can be omitted in which case it will be deduced from the context: if the first two colors have no position, the first will receive position~$0$ and the second will receive position ``$1\text{cm}$''. All following ones receive the last encountered mesh width. Note that non-uniform positions make a real difference in conjunction with |colormap access=piecewise const|.

	The precise input format is described in the following section.

\subsubsection{Colormap Input Format Reference}
\label{sec:colormap:input:format}%
Each entry in \meta{color specification} has the form 

	\meta{color model}|(|\meta{position}|)=(|\meta{arguments}|)| or

	\meta{special mode}|(|\meta{position}|)=(|\meta{argument}| of |\meta{colormap name}|)|

where the most common form is to specify a color using a \meta{color model} like |rgb=(0,0.5,1)|. The \meta{special mode}s are discussed later in Section~\ref{sec:pgfplots:colormaps:based:on:others} on page~\pageref{sec:pgfplots:colormaps:based:on:others}; they are useful to access colors of existing colormaps. The \meta{position} argument is optional and defaults to $0$ for the first color, $1\text{cm}$ for the second, and an automatically deduced mesh grid for all following ones. The number range of \meta{position} is arbitrary. Note that \PGFPlots\ merely remembers the relative distances of the \meta{positions}, not their absolute values. Consequently, a color map with positions $0,1,2$ is equivalent to one with $0,10,20$ or $-10,0,10$ or $-1100,-1000,-900$. \PGFPlots\ maps the input positions to the range $[0,1000]$ internally and works with these numbers. Each new color must have a \meta{position} which is larger than the preceding one.

Available choices for \meta{color model} are
% ATTENTION : a VERY similar description (actually: the same) is in sec:surf:explicit:color
% maintain both; the syntax is different
\begin{description}
\item \declareandlabel{rgb} which expects \meta{arguments} of the form |(|\meta{red}|,|\meta{green}|,|\meta{blue}|)| where each component is in the interval $[0,1]$,
\item \declareandlabel{rgb255} which is similar to |rgb| except that each component is expected in the interval |[0,255]|,
\item \declareandlabel{gray} in which case \meta{arguments} is a single number in the interval $[0,1]$,
\item \declareandlabel{color} in which case \meta{arguments} contains a predefined (named) color like `|red|' or a color expression like `|red!50|',
\item \declareandlabel{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]$,
\item \declareandlabel{cmyk255} which is the same as |cmyk| but expects components in the interval $[0,255]$,
\item \declareandlabel{cmy} which expects \meta{arguments} of the form |(|\meta{cyan}|,|\meta{magenta}|,|\meta{yellow}|)| where each component is in the interval $[0,1]$,
\item \declareandlabel{hsb} which expects \meta{arguments} of the form |(|\meta{hue}|,|\meta{saturation}|,|\meta{brightness}|)| where each component is in the interval $[0,1]$,
\item \declareandlabel{Hsb} which is the same as |hsb| except that \meta{hue} is accepted in the interval $[0,360]$ (degree),
\item \declareandlabel{HTML} which is similar to |rgb255| except that each component is expected to be a hex number between |00| and |FF|,
\item \declareandlabel{wave} which expects a single wave length as numeric argument in the range $[363,814]$.
\end{description}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		colormap={bw}{gray(0cm)=(0); gray(1cm)=(1)}]
	\addplot+[scatter,only marks,
		 domain=0:8,samples=100]
		{exp(x)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

The choice of \meta{positions} influences the processing time: a uniform distance between the \meta{positions} allows more efficient lookup than non-uniform distances. If there is no visual difference and it does not hurt with respect to the number of data points, prefer color maps with uniform distances over non-uniform maps. Note that non-uniform maps make a huge difference in conjunction with |colormap access=piecewise constant|. \PGFPlots\ provides a simple way to map a non-uniform color definition to a uniform one: write the target mesh width as \emph{first item} in the specification. \PGFPlots\ will perform this interpolation automatically, provided all encountered \meta{positions} can be mapped to the target grid:
	\index{Color maps!Non uniform}

\begin{codeexample}[code only]
% non uniform spacing example: the mesh width is provided as first
% part of the specification.
\pgfplotsset{colormap={violetnew}%
	{[1cm] rgb255(0cm)=(25,25,122) color(1cm)=(white) rgb255(5cm)=(238,140,238)}}
\end{codeexample}
\pgfplotsshowcolormapexample{[1cm] rgb255(0cm)=(25,25,122) color(1cm)=(white) rgb255(5cm)=(238,140,238)}

\noindent In this last example, the mesh width has been provided explicitly and \PGFPlots\ interpolates the missing grid points on its own. It is an error if the provided positions are no multiple of the mesh width. 


\subsubsection{The Colorspace of a Colormap}

\emph{Attention:} this section is essentially superfluos if you have configured the |xcolor| package to override color spaces globally (for example by means of |\usepackage[cmyk]{xcolor}| before loading \PGFPlots), see the end of this sub--section.

Even though a |colormap| accepts lots of color spaces on \emph{input} (in fact, it accepts most or all that |xcolor| provides), the \emph{output} color of a colorspace has strict limitations. The output colorspace is the one in which \PGFPlots\ interpolates between two other colors. To this end, it transforms input colors to the output color space. The output colorspace is also referred to as ``the colorspace of a colormap''.

There are three supported color spaces for a |colormap|: the GRAY, RGB, and CMYK color spaces. 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 |gray|, |rgb| or |cmyk|, this specific color space is used and every color is converted automatically.
\begin{pgfplotskey}{colormap default colorspace=\mchoice{auto,gray,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 impossible 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.

	Note that this option has \emph{no effect} if you told |xcolor| to override the color space globally. More precisely, the use of 
\begin{codeexample}[code only]
\usepackage[cmyk]{xcolor}
\end{codeexample}
	or, alternatively,
\begin{codeexample}[code only]
\selectcolormodel{cmyk}
\end{codeexample}
	will cause all colors to be converted to |cmyk|, and \PGFPlots\ honors this configuration. Consequently, both these statements cause all colors to be interpolated in the desired color space, and all output colors will use this colorspace. This is typically exactly what you need.

\end{pgfplotskey}

\subsubsection{Predefined Colormaps}
Available color maps are shown below.

\end{pgfplotskey}

\begin{stylekey}{/pgfplots/colormap/viridis}
	A style which installs the colormap ``viridis'' which has been defined by St\'efan van der Walt and Nathaniel Smith for |Matplotlib|. It is designated to be the default |colormap| for |Matplotlib| starting with version~$2.0$ and is released under the CC0\footnote{\url{https://creativecommons.org/about/cc0}}. 

	The choice |viridis| is a downsampled copy included in \PGFPlots.

\begin{codeexample}[code only]
\pgfplotsset{
	colormap name=viridis,
}
\end{codeexample}
	\pgfplotsshowcolormap{viridis}

	This |colormap| has considerably better properties compared to other choices:
	\begin{itemize} 
	\item its color distribution is perceptually uniform (compare the definition in the link below),
	\item it is suitable for moderate forms of color blindness,
	\item it is still good when printed in black and white.
	\end{itemize}
	Details about these properties can be found in \url{http://bids.github.io/colormap}.

	Please use the the choice |colormap name=viridis| as this makes uses of the predefined colormap whereas |colormap/viridis| will redefine it.

	There is also a high resolution copy of |viridis| which is called |colormap/viridis high res| in the |colormaps| library. It resembles the original resolution of the authors, but it is visually almost identically to |viridis| and requires less resources in \TeX.
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/hot}
	A style which installs the colormap
\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 a preconfigured color map.
\end{stylekey}

\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}

	\pgfplotsshowcolormap{jet}

	\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}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colormap/bluered]
	\addplot+[scatter,
		 scatter src=x,samples=50]
		{sin(deg(x))};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	\paragraph{Remark:} 
	The style |bluered| (re-)defines the color map and activates it. \TeX\ will be slightly faster if you call |\pgfplotsset{colormap/bluered}| in the preamble (to create the color map once) and use |colormap name=bluered| whenever you need it. This remark holds for every color map style which follows. But you can simply ignore this remark.
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/cool}
	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 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 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 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{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).

	The first argument is the name of a (defined) colormap, the second the rightmost dimension of the specification. The result will be stored in \meta{\textbackslash macro}.
\begin{codeexample}[]
	% convert `hot' -> \result
	\pgfplotscolormaptoshadingspec{hot}{8cm}\result
	% define and use a shading in pgf:
	\def\tempb{\pgfdeclarehorizontalshading{tempshading}{1cm}}%
	% where `\result' is inserted as last argument:
	\expandafter\tempb\expandafter{\result}%
	\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 add the macro definition \texttt{\textbackslash def\textbackslash pgfplotscolormaptoshadingspectorgb\{0\}} to your preamble.}.
\end{command}

\begin{command}{\pgfplotscolorbardrawstandalone\oarg{options}}
	A command which draws a |tikzpicture| and a |colorbar| using the current color bar settings inside of it. Its purpose is to simplify the documentation.
	
	Since this |colorbar| is a ``standalone'' picture, it defines the following options
\begin{codeexample}[code only]
	point meta min=0,
	point meta max=1000,
	parent axis width/.initial=6cm,
	parent axis height/.initial=6cm,
\end{codeexample}
	before it evaluates \meta{options} and draws the colorbar.
\end{command}

\begin{command}{\pgfplotscolormaptodatafile\oarg{options}\marg{colormap name}\marg{output file}}
	Allows to export |colormap| data to a file.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[y=1cm,table/col sep=comma]
	\pgfplotscolormaptodatafile{hot}{hot.dat}
	\addplot[red,mark=|] table[y index=1] {hot.dat};
	\addplot[green,mark=|] table[y index=2] {hot.dat};
	\addplot[blue,mark=|] table[y index=3] {hot.dat};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[y=1cm,table/col sep=comma]
	\pgfplotscolormaptodatafile{viridis}{viridis.dat}
	\addplot[red] table[y index=1] {viridis.dat};
	\addplot[green] table[y index=2] {viridis.dat};
	\addplot[blue] table[y index=3] {viridis.dat};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	Valid \meta{options} are
	\begin{pgfplotskey}{/pgfplots/colormap/output each nth=\meta{num} (initially 1)}
		Allows to downsample the color map by writing only each \meta{num}'s entry.
	\end{pgfplotskey}
	\begin{pgfplotskey}{/pgfplots/colormap/output format=\mchoice{cvs,native} (initially csv)}
		The choice \declaretext{csv} generates a csv file where the first column is the offset of the color map and all following are the color components.

		The choice \declaretext{native} generates a \TeX\ file which can be |\input| in order to define the colormap for use in \PGFPlots.
	\end{pgfplotskey}
\end{command}


Note that there are \emph{more available choices} of colormaps in the associated libraries, name in the |colorbrewer| library and in the |colormaps| library which need to be loaded by means of |\usepgfplotslibrary{colorbrewer,colormaps}|.

\subsubsection{Building Colormaps based on other Colormaps}
\label{sec:pgfplots:colormaps:based:on:others}

{%
\tikzset{
	/pdflinks/search key prefixes in/.add={}{,/pgfplots/of colormap/},
}%
A colormap definition of sorts |colormap=|\marg{name}\marg{color specification} typically consists of \meta{color specifications} made up from single colors, each with its own \meta{color model}. As outlined in Section~\ref{sec:colormap:input:format}, each entry in \meta{color specification} has the form 

	\meta{color model}|(|\meta{position}|)=(|\meta{arguments}|)| or

	\meta{special mode}|(|\meta{position}|)=(|\meta{argument}| of |\meta{colormap name}|)|.

\noindent This section explains how to make use of \meta{special mode} in order to build |colormap|s based on existing |colormap|s. To this end, \PGFPlots\ offers the following values inside of a \meta{color specification}:

\begin{enumerate}

	\item

	\declareandlabel{samples of colormap}|(|\meta{position}|)=(|\meta{number}| of |\meta{colormap name}|)| or\\
	\declaretext{samples of colormap}|(|\meta{position}|)=(|\meta{number}|)| or\\
	\declaretext{samples of colormap}|(|\meta{position}|)={|\meta{number}| of |\meta{colormap name}|, |\meta{options}|}|
	\index{samples of colormap!In colormap specification}%

	This method takes a \meta{colormap name} on input, samples \meta{number} colors from it (using a uniform mesh width) and inserts it into the currently built |colormap|. It is equivalent to the choice |colors of colormap||(|\meta{position}|)=(0,h,...,1000)| with |h| chosen such that you get \meta{number} samples positioned at an equidistant grid.

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		samples of colormap=(4 of viridis)
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		samples of colormap=(4 of viridis)
	},
	colorbar horizontal,
	colormap access=map]
\end{codeexample}

	The special suffix ``| of |\meta{colormap name}'' is optional; it defaults to the current value of |colormap name|:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		samples of colormap=(4)
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		samples of colormap=(4)
	},
	colorbar horizontal,
	colormap access=map]
\end{codeexample}

	The argument can be surrounded by round braces or curly braces, both is accepted. \PGFPlots\ also accepts a sequence of options inside of the argument and curly braces are best applied if options are needed:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{%
        samples of colormap={
            5 of viridis,
            target pos={0,800,850,950,1000},
        }
    },
    colorbar horizontal,
    colormap access=map]
\end{codeexample}
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{%
		% simpler alternative:
		% of colormap={viridis,target pos={...}}
        samples of colormap={
            5 of viridis,
            target pos={0,400,500,700,800,1000},
            sample for=const,
        }
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
		
	The use of options inside of the argument is discussed in the next sub-section, see |of colormap| and |target pos|.

	As with normal color definitions, the \meta{position} argument is optional and can be omitted. If it is given, it is used for the first encountered item in the list, all others are deduced automatically. If both |target pos| and \meta{position} are given, \meta{position} is ignored.

	Note that \PGFPlots\ offers a special syntax for |target pos| and a sampled colormap:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{%
        of colormap={
            viridis,
            target pos={0,400,500,700,800,1000},
            sample for=const,
        }
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
	This syntax also samples colors from the source colormap (|viridis| here). It chooses enough samples to satisfy the given |target pos|; see the documentation for `|of colormap|' for details.

	\item
	\declareandlabel{index of colormap}|(|\meta{position}|)=(|\meta{index}| of |\meta{colormap name}|)| or\\
	\declaretext{index of colormap}|(|\meta{position}|)=(|\meta{index}|)|
	\index{index of colormap!In colormap specification}%

	This key allows to identify a \emph{single} color of \meta{colormap name} and use it as part of \meta{color specification}. The \meta{index} is a numeric index $0,1,\dotsc,N-1$ where $N$~is the size of \meta{colormap name}.

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		color=(green),
		index of colormap=(2 of viridis)
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}

	Note that |index of colormap| is also available as key for drawing operations.

	All special remarks of |samples of colormap| (like curly braces, option list support, positions) apply here as well.

	\item
	\declareandlabel{indices of colormap}|(|\meta{position}|)=(|\meta{list of indices}| of |\meta{colormap name}|)| or\\
	\declaretext{indices of colormap}|(|\meta{position}|)=(|\meta{list of indices}|)|
	\index{indices of colormap!In colormap specification}%

	A convenience key which is equivalent to a sequence of |index of colormap||(|\meta{position}|)|, one for each element in \meta{list}. The \meta{list} is evaluated using |\foreach|. Note that you need round braces around the argument.

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		indices of colormap=(0,5,10,12,
		  \pgfplotscolormaplastindexof{viridis}
		  of viridis)
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
	
	All special remarks of |samples of colormap| (like curly braces, option list support, positions) apply here as well.
	\item
	\declareandlabel{color of colormap}|(|\meta{position}|)=(|\meta{value}| of |\meta{colormap name}|)| or\\
	\declaretext{color of colormap}|(|\meta{position}|)=(|\meta{value}|)|
	\index{color of colormap!In colormap specification}%

	This key allows to interpolate a color within \meta{colormap name} and use the result as part of \meta{color specification}. The interpolation point is a floating point number in the range $[0,1000]$ and is interpolated using |colormap access=map| (i.e.\ using piecewise linear interpolation).

	Note that |color of colormap| is also available as key for drawing operations.

	All special remarks of |samples of colormap| (like curly braces, option list support, positions) apply here as well.
	\item 
	\declareandlabel{colors of colormap}|(|\meta{position}|)=(|\meta{list}| of |\meta{colormap name}|)| or\\
	\declaretext{colors of colormap}|(|\meta{position}|)=(|\meta{list}|)| or\\
	\declaretext{colors of colormap}|(|\meta{position}|)={|\meta{list}| of |\meta{colormap name}|, |\meta{options}|}|
	\index{colors of colormap!In colormap specification}%

	A convenience key which is equivalent to a sequence of |color of colormap||(|\meta{position}|)|, one for each element in \meta{list}. The \meta{list} is evaluated using |\foreach|. Note that you need round braces around the argument.

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
	  colors of colormap=(0,400,800,900,
	  	1000 of viridis)
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}

	Note that |colors of colormap| is also available during |cycle list| definitions.

	All special remarks of |samples of colormap| (like curly braces, option list support, positions) apply here as well.


	\item \declaretext{of colormap}|(|\meta{position}|)=(|\meta{colormap name}|, |\meta{options}|)| 
	
	Builds a new |colormap| by \emph{sampling} enough colors from the input |colormap name|. This mode is one of two methods which samples colors from another |colormap|; it is to be preferred if you want to assign |target pos|. See also |samples of colormap|; it is simpler if you just want to specify a number of samples.

	The syntax `|of colormap=|' is most useful if you want to draw samples from another colormap \emph{at specific positions}:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{%
        of colormap={
            viridis,
            target pos={0,400,500,700,800,1000},
        }
    },
    colorbar horizontal,
    colormap access=map]
\end{codeexample}
	Here, \PGFPlots\ parses the \meta{options}. Each unidentified option is treated as either a value of `|colormap name|' or as a style argument which defines a |colormap| like |colormap/PuOr|. The previous example identifies |colormap name=viridis| (since |viridis| is no known option) and assigns |target pos|. There are $6$~samples which make up the colormap, these are drawn from |viridis|. Note that you do not need to specify a \meta{colormap name} in this context. If it is missing, the current value of |colormap name| (i.e.\ the current colormap) will be used.

	Similarly, `|of colormap|' can sample a |colormap| for use with |colormap access=const|:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{%
        of colormap={
            viridis,
            target pos={0,400,500,700,800,1000},
            sample for=const,
        }
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
	Note that you \emph{need} to write |sample for=const| in this context such that \PGFPlots\ knows that the result is to be used in conjunction with |colormap access=const|. The details are specified below.

	As with all colormap building blocks, the |target pos| can have an arbitrary number range. However, the absolute values are meaningless; they are always mapped to the range $[0,1000]$. Only their relative distances are of importance when it comes to the |colormap| as such:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		of colormap={viridis,
			target pos={-10,-3,0,1,2},
            sample for=const,
		}
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
	However, if the |point meta| range equals the colormap definition range, you see that they fit exactly:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		of colormap={viridis,
			target pos={-10,-3,0,1,2},
            sample for=const,
		}
	},
	point meta min=-10,point meta max=2,
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
	Note that you can use |xtick=data| or |ytick=data| inside of the |colorbar| styles in order to place tick labels at the |colormap|'s positions:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		of colormap={viridis,
			target pos={-10,-3,0,1,2},
            sample for=const,
		}
	},
	point meta min=-10,point meta max=2,
	colorbar horizontal,
	colorbar style={xtick=data},
	colormap access=const]
\end{codeexample}

	Finally, `|of colormap|' can be used to \emph{copy} another |colormap|: if there are no suitable hints how to build a new |colormap|, \PGFPlots\ copies the input map:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		of colormap={viridis},
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}

	The \meta{options} are accepted by all colormap building blocks: you can also specify them after |samples of colormap| or |colors of colormap| if needed.
	
	The following options are available:

\begin{pgfplotskey}{of colormap/target pos=\marg{position(s)} (initially empty)}
	Allows to define the \meta{position} for zero, one, or more of the involved colors. An empty value means to use the argument in round braces `|(|\meta{position}|)|' in the definition, for example the value $100$ in |color of colormap(100)=(4)|. This is sufficient if there is just one color involved. However, if |target pos| has a non-empty value, it overrides the |(|\meta{position}|)| argument.

	The key |target pos| is primarily intended to provide positions for more than one color definition, in particular in the context of `|of colormap|'. In this context, as many \meta{position(s)} as specified are used. 
	
	If you have |colors of colormap| and a non-empty value of |target pos|, \PGFPlots\ will use as many |target pos|itions as available. If there are too few to cover all involved colors, the remaining ones are deduced automatically. 
	More precisely: \PGFPlots\ will use the current mesh width as distance to the previous position. The ``current mesh width'' is defined as the smallest difference between adjacent positions.
	Excess positions will be ignored (and a warning is written into the log file).

	Note that |target pos| requires attention when used together with |colormap access=const|: in this case, there are \emph{intervals} with constant color and the positions become interval boundaries. Consequently, $N$ elements in |target pos| make up $N-1$ different colors!

	Note that |target pos| as option to |samples of colormap| is also possible. However, you have to specify all required positions and it is an error if the number does not match. If you also combine this case with |sample for=const|, you need $N+1$ positions for $N$ samples. 

\end{pgfplotskey}

\begin{pgfplotskey}{of colormap/sample for=\mchoice{default,const} (initially default)}
	This key allows to configure |samples of colormap| such that the resulting |colormap| is suitable for dedicated values of |colormap access|. 

	In particular, it allows to optimize \meta{colormap definitions} which rely on \emph{sampling} for the case |colormap access=const|.

	Note that the case |colormap access|$\neq$|const| typically requires no modification to this key and works best with the defaults.

	The strategy |colormap access=const| means that colors are associated with entire \emph{intervals} and no longer with single positions in the |colormap|. In this context, you have to write |sample for=const| such that \PGFPlots\ handles that correctly.
	
	Here is the reference of |colormap|s and their significance with respect to |sample for|:
	\begin{itemize}
		\item In general, a |colormap| can be used with any value of |colormap access|. If there are no positions in the \meta{colormap definition} (neither in round braces nor in |target pos|), this works out of the box without any special attention.
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		samples of colormap={
			5 of viridis,
		}
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
		\item As soon as there are positions, \PGFPlots\ has a conflict if the colormap is used in the context of |colormap access=const|: it cannot enlarge the displayed limit, but it cannot respect both the given positions \emph{and} the required number of colors! It has the choice to either omit one color, or to add an artifical position and rescale all other positions.
		\item The default strategy in \PGFPlots\ in the presence of |colormap access=const| and input positions is: \PGFPlots\ chooses to keep the input positions and omit one color.
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		of colormap={
			viridis,
			target pos={0,500,850,950,1000},
		}
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}

		Technically, this means that it implicitly sets |colormap access/extra interval width=0| (the default is |colormap access/extra interval width=h|). The color associated with $1000$ has no interval and is essentially invisible.

		Restoring |colormap access/extra interval width=h| results in rescaled positions which is typically not what you want:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		samples of colormap={
			5 of viridis,
			target pos={0,500,850,950,1000},
		}
	},
	colormap access/extra interval width=h,
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
		\item Finally, \PGFPlots\ offers |sample for=const|. 
		
	Applying |sample for=const| to `|of colormap|' ensures that any given positions are respected. To this end, it reduces the number of available colors, but modifies the sampling procedure such that the entire input color range is visible in the result:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		of colormap={
			viridis,
			target pos={0,500,850,950,1000},
			sample for=const,
		}
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
	Here, the result has $4$ colors, but the rightmost color is also the rightmost color of the input map |viridis|. Note that |of colormap| has assigned an invisible color to the position $1000$: this dummy color is defined to be the rightmost color of |viridis|. That means that if you define a |colormap| with |sample for=const| and use it with |colormap access=map|, the right end of the interval will be longer than expected:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		of colormap={
			viridis,
			target pos={0,500,850,950,1000},
			sample for=const,
		}
	},
	colorbar horizontal,
	colormap access=map]
\end{codeexample}

	The strategy |sample for=const| applied to |samples of colormap| works in a similar way. Keep in mind that this combination requires to either omit |target pos| or to add \emph{exactly} $N+1$ target positions:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		samples of colormap={
			5 of viridis,
			target pos={0,100,500,850,950,1000},
			sample for=const,
		}
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}

		This results in correctly respected positions and a fully respected range of the input colormap.
	\end{itemize}

	The key |sample for| applies whenever a \meta{colormap definition} involves sampling (that means: only for |of colormap| and |samples of colormap|). It does not apply for explicitly fixed colors. Its effect is that the number of samples is reduced by~$1$ and the last provided sample is replicated once.

	See also |colormap access/extra interval width|.
\end{pgfplotskey}

\begin{pgfplotskey}{of colormap/colormap access=\marg{argument}}
	 An alias for |/pgfplots/colormap access=|\marg{argument}.
\end{pgfplotskey}

\begin{pgfplotskey}{of colormap/source range=\marg{min:max} (initially 0:1000)}
	 Defines the source range for interpolation-based specifications, i.e.\ for |color of colormap| and |const color of colormap|. It defaults to |0:1000| which means that only values in the interval $[0,1000]$ can be provided. 

	 Changing the value allows to use any number range in order to identify numbers.
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
	  colors of colormap={
	    -30000,-10000,0,100000,110000 of viridis, 
	  source range=-30000:120000}
	},
	colorbar horizontal,
	colormap access=const]
\end{codeexample}
\end{pgfplotskey}

%\begin{pgfplotskey}{of colormap/source name=\marg{colormap name} (initially empty)}
%	The name of the source color map. An empty value means ``use the current value of |colormap name|''.
%\end{pgfplotskey}


\noindent Note that these building blocks can be combined as often as needed. This allows to combine different colormaps:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	point meta min=-7046,
	point meta max=2895,
	colormap={whiteblue}{color=(blue) color=(white)},
	colormap={gb}{color=(green) color=(yellow) 
		color=(brown)},
	colormap={CM}{
		of colormap={
			whiteblue, 
			target pos={-7046,-6000,-5000,-3000,
				-1000,-750,-500,-250,-100,-50,0},
			sample for=const,
		},
		of colormap={
			gb, 
			target pos={10,100,200,500,1000,1100,
				1200,1500,2000,2895},
			sample for=const,
		}
	},
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
\noindent The previous example first defines the two simple colormaps |whiteblue| and |gb|. These are merely used as building blocks; they are not used for the visualization. Finally, the colormap |CM| consists of two |of colormap|
 specifications which resample the building blocks and assign specific |target pos|itions.

\begin{pgfplotskeylist}{%
	of colormap/target pos min=\marg{lower limit} (initially empty),%
	of colormap/target pos min*=\marg{lower limit} (initially empty),%
	of colormap/target pos max=\marg{upper limit} (initially empty),%
	of colormap/target pos max*=\marg{upper limit} (initially empty)}%
	
	These keys allow to \emph{modify} the argument of |target pos|. Their primary use is to simplify writing style definitions. Consequently, most users may want to ignore these keys and skip their documentation. The keys are unnecessary if the argument of |target pos| is used directly.
	
	The versions without star (|target pos min| and |target pos max|) discard all elements of |target pos| which are outside of the bounds. The starred versions (|target pos min*| and |target pos max*|) also discard all which do not fit, but they ensure that the limit is part of |target pos| after the filtering.
	
	These filtering limits come in handy if you want to select matching positions from a previously defined |target pos|, for example if the same |target pos| is part of a reusable style:
\begin{codeexample}[width=8cm]
\pgfplotsset{
	of colormap/ocean height/.style={
		target pos={-12000,-10000,-6000,-5000,-3000,
			-1000,-750,-500,-250,-100,-50,0,10,100,
			200,500,1000,1100,1200,1500,2000,4000,
			6000,8000},
	},
}
\pgfplotscolorbardrawstandalone[
  point meta min=-7046,
  point meta max=2895,
  colormap={whiteblue}{color=(blue) color=(white)},
  colormap={gb}{color=(green) color=(yellow) 
      color=(brown)},
  colormap={CM}{
      of colormap={
          whiteblue, 
          ocean height,
          target pos min*=
           \pgfkeysvalueof{/pgfplots/point meta min},
          target pos max=0,
          sample for=const,
      },
      of colormap={
          gb, 
          ocean height,
          target pos min=0.1,
          target pos max*=
           \pgfkeysvalueof{/pgfplots/point meta max},
          sample for=const,
      }
  },
  colorbar horizontal,
  colormap access=const]
  
\end{codeexample}
	\noindent The example defines a style named `|ocean height|' with a suitable list of positions somewhere in the document. Then, it defines a colormap `|CM|' which makes use of these keys -- but only in the range $[-7046,2895]$, and with a special combination of two other |colormap|s. The first |of colormap| specification selects only those target positions which fall in the range $[-7046,0]$ and ensures that $-7046$ actually becomes an element of |target pos|. The second |of colormap| specification selects all in the range $[0.1,2895]$ and ensures that $2895$ becomes an element of |target pos|. Note that the $0.1$ merely serves as indicator to \emph{not} select $0$ again. Thus, the selection is essentially equivalent to 
\begin{codeexample}[code only]
...
target pos={-7046,-6000,-5000,-3000,-1000,-750,-500,-250,-100,-50,0}
...
target pos={10,100,200,500,1000,1100,1200,1500,2000,2895}
\end{codeexample}
	with the exception that the predefined style defined a list of suitable positions.

	\PGFPlots\ uses these keys in order to implement |contour filled|.
\end{pgfplotskeylist}

	\item
	\declareandlabel{const color of colormap}|(|\meta{position}|)=(|\meta{value}| of |\meta{colormap name}|)|.
	\index{const color of colormap!In colormap specification}%

	This key is almost the same as |color of colormap| mentioned above, but it uses the same functionality as |colormap access=piecewise constant| while it determines colors from the \emph{source} color map (including |colormap access/extra interval width|). Note that the resulting colormap can still be used with any value of |colormap access|, including both |colormap access=const| and |colormap access=map|.

	Note that |const color of colormap| is also available as key for drawing operations.

	All special remarks of |samples of colormap| (like curly braces, option list support, positions) apply here as well.
	\item 
	\declareandlabel{const colors of colormap}|(|\meta{position}|)=(|\meta{list}| of |\meta{colormap name}|)|
	\index{const colors of colormap!In colormap specification}%

	A convenience key which is equivalent to a sequence of |const color of colormap(|\meta{position}|)|, one for each element in \meta{list}. The \meta{list} is evaluated using |\foreach|.

	Note that |const colors of colormap| is also available during |cycle list| definitions.

	All special remarks of |samples of colormap| (like curly braces, option list support, positions) apply here as well.
	
%-------------
\end{enumerate}

\begin{pgfplotskey}{colormap access/extra interval width=\marg{fraction} (initially h)}
	\paragraph{Attention:} this key is supposed to be a technical part of the implementation. You may want to skip its documentation as it typically works out of the box. You only need to respect |sample for|.

	This key applies \emph{only} to |colormap access=piecewise constant|: it ensures that each color in the |colormap| receives its own \emph{interval}. This ensures that each color is actually visible in the output. Thus, each provided color resembles an \emph{interval}. This is different from |colormap access=map| where each provided color resembles an \emph{interval boundary}.

	Normally, \PGFPlots, activates this feature if and only if it has automatically computed positions. Consequently, the following example implicitly uses |extra interval width=h| (the default):
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		color=(blue)
		color=(red)
		color=(black)
	},
	colorbar horizontal,
	colorbar style={xtick=data},
	colormap access=const]
\end{codeexample}
	
	As soon as you provide positions manually, \PGFPlots\ defaults to |extra interval width=0| in order to respect the input settings:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		color(0)=(blue)
		color(500)=(red)
		color(1000)=(black)
	},
	colorbar horizontal,
	colorbar style={xtick=data},
	colormap access=const]
\end{codeexample}
	\noindent Note that the positions make up the input nodes for the |colormap| with the consequence that the last color is \emph{unused}; it merely serves as interval boundary. In this context, ``provide manually'' means positions in round braces or a non-empty value of |target pos|. 
	
	In order to override the input positions and get an extra interval, you have to set the option:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={example}{%
		color(0)=(blue)
		color(500)=(red)
		color(1000)=(black)
	},
	colorbar horizontal,
	colorbar style={xtick=data},
	colormap access/extra interval width=h,
	colormap access=const]
\end{codeexample}
	Note how the extra interval of |colormap access=const| modifies the positions of the colormap definition: they are all shifted to the left and the chosen input positions are scaled accordingly. This becomes more apparent in the following example.
	First, we generate a colormap with the default settings which disables the extra interval, but omits the last (brightest) color:

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={nonuniform}{
		of colormap={
			viridis,
			target pos={0,200,300,500,700,1000}
		}
	},
	colorbar horizontal,
	colormap access=const,
	colorbar style={xtick=data,font=\tiny,
		/pgf/number format/precision=0},
	colormap access=const]
\end{codeexample}

	Next, we explicitly enable the extra interval and see that the input positions are scaled to the left. Note that they keep their relative distances, but the last color of the colormap is finally visible:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={nonuniform}{
		of colormap={
			viridis,
			target pos={0,200,300,500,700,1000}
		}
	},
	colorbar horizontal,
	colormap access=const,
	colormap access/extra interval width=h,
	colorbar style={xtick=data,font=\tiny,
		/pgf/number format/precision=0},
	colormap access=const]
\end{codeexample}

	The last example relies on |of colormap| and a \emph{sampling} procedure. In this context, \PGFPlots\ offers |sample for=const| which results in the expected look:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
	colormap={nonuniform}{
		of colormap={
			viridis,
			target pos={0,200,300,500,700,1000},
			sample for=const,
		}
	},
	colorbar horizontal,
	colormap access=const,
	colorbar style={xtick=data,font=\tiny,
		/pgf/number format/precision=0},
	colormap access=const]
\end{codeexample}
	Please refer to the documentation of |sample for|.
	
	The default width of this interval is the mesh width of the color map (the value \declaretext{h}), i.e.\ it will always be as large as the other intervals. If the color map has non-uniform distances, the smallest encountered mesh width is used for the extra interval. This can be seen if we omit the key and add some artifical color at the right end manually -- we only need to ensure that the rightmost interval has the correct length. In our example above, the smallest mesh width is $100$, so we can generate an equivalent result by means of
	\index{Color maps!Non uniform}
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={nonuniform}{
        of colormap={
            viridis,
            target pos={0,200,300,500,700,1000}
        }
		color(1100)=(red)
    },
    colorbar horizontal,
    colormap access=const,
    colorbar style={xtick=data,font=\tiny,
        /pgf/number format/precision=0},
    colormap access=const]
\end{codeexample}
	\noindent As already mentioned, |colormap access=const| ignores the rightmost color (``|red|''). Note that this approach is almost the same as the internal implementation of |sample for=const|.

	The value of |colormap access/extra interval width=|\meta{fraction} can also be used to customize the width of the artifical interval: it is a fraction of the total width and accepted values are $0\le $\meta{fraction}$\le 0.9$ where $0$ disables the extra interval and $0.9$ corresponds to $90\%$ of the resulting width. 
	Any non-$0$ value for \meta{fraction} creates an extra interval and its width is \meta{fraction} percent of the entire color map.
	The special magic value |colormap access/extra interval width=|\declaretext{h} will use the colormap's mesh width. If the colormap has non-uniform distances, it will use the smallest encountered mesh width. This is the default.

	Note that \meta{fraction} is a property of the |colormap|. The key defines it for the \emph{current} color map only. Defining a new |colormap| uses the default width for the new |colormap| (but keeps the configured value for the old |colormap|).

	\paragraph{Attention:} at the time of this writing, uniform color maps only support the default interval width `|h|' and \meta{fraction}$=0$, further customization is only possible for non-uniform color maps. If you ever need to work around this limitation, you should file a feature requests and move one of your color position until the colormap becomes a non-uniform colormap.
	
\end{pgfplotskey}

}%

\subsubsection{Choosing a Colormap Entry as Normal Color}

\begin{pgfplotskeylist}{%
	color of colormap=\meta{value},
	color of colormap=\meta{value} of \meta{colormap name}}%
	[See also Section~\ref{sec:pgfplots:colormaps:based:on:others} on page~\pageref{sec:pgfplots:colormaps:based:on:others} for how to employ this within |colormap| definitions]
	
	Defines the \tikzname\ |color| to be the \meta{value} of \meta{colormap name}. If \meta{colormap name} is omitted, the value of |colormap name| is evaluated (i.e.\ the current colormap is used).

	The argument \meta{value} is expected to be a number in the range $[0,1000]$ where $0$ resembles the lower end of the color map and $1000$ the upper end.

	\pgfkeysgetvalue{/pgfplots/colormap name}\colormapname
	Current colormap (\colormapname): \pgfplotsshowcolormap{\colormapname}

\begin{codeexample}[]
\tikz\fill[color of colormap={800}, thick,
	draw=.!60!black]
	(0,0) -- (1,1) -- (2,1) circle (10pt);
\end{codeexample}
	
	The key computes the requested color and calls |color=.|. Keep in mind that the magic color name `|.|' always reflects the ``current color'', i.e.\ the result of |color=|\meta{some color}. Also keep in mind that |color| is a \tikzname\ command which merely defines the color, you also have to provide one of `|draw|' or `|fill|' such that it has an effect. Since `|.|' is a normal color, we can write |draw=.!60!black| to combine it with another color. 

	viridis: \pgfplotsshowcolormap{viridis}

\begin{codeexample}[]
\pgfplotsset{colormap name=viridis}
\tikz\fill[color of colormap={1000},thick,
	draw=.!60!black] 
	(0,0) -- (1,1) -- (2,1) circle (10pt);
\end{codeexample}

\begin{codeexample}[]
\tikz\fill[color of colormap={300 of viridis},thick,
	draw=.!60!black] 
	(0,0) -- (1,1) -- (2,1) circle (10pt);
\end{codeexample}
	
	The argument \meta{colormap name} is either a valid argument of |colormap name| \emph{or} a style name like |colormap/cool|:

	cool: \pgfplotsshowcolormap{cool}

\begin{codeexample}[]
\tikz\fill[color of colormap={300 of colormap/cool}, 
	thick,draw=.!60!black]
	(0,0) -- (1,1) -- (2,1) circle (10pt);
\end{codeexample}

	This last syntax allows to evaluate colormaps lazily. However, if you have many references to the same colormap, it makes sense to write |\pgfplotsset{colormap/cool}| first followed by many references to |color of colormap={... of cool}| in order to avoid unnecessary lazy evaluations.

	It is possible to write lots of invocations without an explicit \meta{colormap name}, i.e.\ lots of invocations of sorts |color of colormap=|\meta{value}. They will all use the |colormap name| which is active at that time.

	Note that there are actually keys with two key prefixes: |/pgfplots/color of colormap| and an alias |/tikz/color of colormap|. This allows to use the keys both for plain \tikzname\ graphics and for \PGFPlots.

	See also |colormap access=map|.
\end{pgfplotskeylist}

\begin{pgfplotskeylist}{%
	index of colormap=\meta{index},
	index of colormap=\meta{index} of \meta{colormap name}}%
	[See also Section~\ref{sec:pgfplots:colormaps:based:on:others} on page~\pageref{sec:pgfplots:colormaps:based:on:others} for how to employ this within |colormap| definitions]

	A variant of |color of colormap| which accesses the \meta{colormap name} by index. Consequently, the argument \meta{index} is an integer number in the range $0,\dotsc,N-1$ where $N$ is the number of colors which define the \meta{colormap name}. A \meta{index} outside of this range is automatically clipped to the upper bound.

\begin{codeexample}[]
\pgfplotsset{colormap/jet}

\foreach \i 
  in {0,...,\pgfplotscolormaplastindexof{jet}}
{
  \tikz\fill[index of colormap={\i of jet},
	thick,
	draw=.!60!black] (0,0) rectangle (10pt,6pt);
}
\end{codeexample}
	
	\begin{command}{\pgfplotscolormapsizeof\marg{colormap name}}
		Expands to the number of colors which make up \meta{colormap name}. 

		If the argument \meta{colormap name} is an unknown colormap, it expands to $0$.
	\end{command}
	\begin{command}{\pgfplotscolormaplastindexof\marg{colormap name}}
		Expands to the last index of \meta{colormap name}, i.e.\ it is a convenience method to access $N-1$. 

		If the argument \meta{colormap name} is an unknown colormap, it expands to $-1$.
	\end{command}

	See also |colormap access=direct|.
\end{pgfplotskeylist}

\begin{pgfplotskeylist}{%
	const color of colormap=\meta{value},
	const color of colormap=\meta{value} of \meta{colormap name}}%
	[See also Section~\ref{sec:pgfplots:colormaps:based:on:others} on page~\pageref{sec:pgfplots:colormaps:based:on:others} for how to employ this within |colormap| definitions]
	
	Defines the \tikzname\ |color| to be the \meta{value} of \meta{colormap name}. If \meta{colormap name} is omitted, the value of |colormap name| is evaluated (i.e.\ the current colormap is used).
	
	This key is almost the same as |color of colormap|, except that it uses |colormap access=piecewise constant| in order to determine the interpolated value.

\end{pgfplotskeylist}

\subsection{Cycle Lists -- Options Controlling Line Styles}

\label{sec:cycle:list}%
\begin{pgfplotskeylist}{cycle list=\marg{list},cycle list name=\marg{name}}
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|.

There are several possibilities to change the currently active |cycle list|:
\subsubsection{Predefined Lists}
	Use one of the predefined lists\footnote{In an early version, these lists were called \texttt{\textbackslash coloredplotspeclist} and \texttt{\textbackslash blackwhiteplotspeclist} which appeared to be unnecessarily long, so they have been renamed. The old names are still accepted, however.},
		\begin{itemize}
			\item \declareandlabel{color} (from top to bottom)
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	stack plots=y,stack dir=minus,
	cycle list name=color]
\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)};
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

			\item \declareandlabel{exotic} (from top to bottom)
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	stack plots=y,stack dir=minus,
	cycle list name=exotic]
\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)};
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

	\item \declareandlabel{black white} (from top to bottom)
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	stack plots=y,stack dir=minus,
	cycle list name=black white]
\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)};
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

	\item \declareandlabel{mark list} (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}

	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)};
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\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)
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	stack plots=y,stack dir=minus,
	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)};
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	\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*]
\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)};
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	\item \declareandlabel{auto} The |cycle list name=auto| always denotes the most recently used cycle list activated by |cycle list| or |cycle list name|.
		\end{itemize}

The definitions of all predefined cycle lists follow (see the end of this paragraph for a syntax description).
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{color}{%
	blue,every mark/.append style={fill=blue!80!black},mark=*\\%
	red,every mark/.append style={fill=red!80!black},mark=square*\\%
	brown!60!black,every mark/.append style={fill=brown!80!black},mark=otimes*\\%
	black,mark=star\\%
	blue,every mark/.append style={fill=blue!80!black},mark=diamond*\\%
	red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\%
	brown!60!black,densely dashed,every mark/.append style={
		solid,fill=brown!80!black},mark=square*\\%
	black,densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\%
	blue,densely dashed,mark=star,every mark/.append style=solid\\%
	red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\%
}
\end{codeexample}
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{black white}{%
	every mark/.append style={fill=gray},mark=*\\%
	every mark/.append style={fill=gray},mark=square*\\%
	every mark/.append style={fill=gray},mark=otimes*\\%
	mark=star\\%
	every mark/.append style={fill=gray},mark=diamond*\\%
	densely dashed,every mark/.append style={solid,fill=gray},mark=*\\%
	densely dashed,every mark/.append style={solid,fill=gray},mark=square*\\%
	densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\%
	densely dashed,every mark/.append style={solid},mark=star\\%
	densely dashed,every mark/.append style={solid,fill=gray},mark=diamond*\\%
}
\end{codeexample}
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{exotic}{%
	teal,every mark/.append style={fill=teal!80!black},mark=*\\%
	orange,every mark/.append style={fill=orange!80!black},mark=square*\\%
	cyan!60!black,every mark/.append style={fill=cyan!80!black},mark=otimes*\\%
	red!70!white,mark=star\\%
	lime!80!black,every mark/.append style={fill=lime},mark=diamond*\\%
	red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\%
	yellow!60!black,densely dashed,
		every mark/.append style={solid,fill=yellow!80!black},mark=square*\\%
	black,every mark/.append style={solid,fill=gray},mark=otimes*\\%
	blue,densely dashed,mark=star,every mark/.append style=solid\\%
	red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\%
}
\end{codeexample}
\begin{codeexample}[code only]
% note that "." is the currently defined Tikz color.
\pgfplotscreateplotcyclelist{mark list}{%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=square*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=triangle*\\%
	every mark/.append style={solid},mark=star\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=diamond*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill!40},mark=otimes*\\%
	every mark/.append style={solid},mark=|\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},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 In this context, a common fill color expression can be customized using |mark list fill|:
\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{command}{\pgfplotsmarklistfill}
	Expands to |\pgfkeysvalueof{||/pgfplots/mark list fill||}|.
\end{command}
\begin{codeexample}[code only]
% note that "." is the currently defined Tikz color.
\pgfplotscreateplotcyclelist{mark list*}{%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=square*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=triangle*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=halfsquare*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=pentagon*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=halfcircle*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill,rotate=180},mark=halfdiamond*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill!40},mark=otimes*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=diamond*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=halfsquare right*\\%
	every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=halfsquare left*\\%
}
\end{codeexample}
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{color list}{%
	red,blue,black,yellow,brown,teal,orange,violet,cyan,green!70!black,magenta,gray}
\end{codeexample}
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{linestyles}{solid,dashed,dotted}
\pgfplotscreateplotcyclelist{linestyles*}{solid,dashed,dotted,dashdotted,dashdotdotted}
\end{codeexample}

\subsubsection{Defining Own Cycle Lists}
The second choice for cycle lists is to provide each entry directly as argument to |cycle list|,
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}[cycle list={%
	{blue,mark=*},
	{red,mark=square},
	{dashed,mark=o},
	{loosely dotted,mark=+},
	{brown!60!black,
		mark options={fill=brown!40},
		mark=otimes*}}
]
\plotcoords
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
	(This example list requires |\usetikzlibrary{plotmarks}|).

	The input format is described below in more detail.

\subsubsection{Defining and Labeling Own Cycle Lists}
The last method for cycle lists is to combine the define \emph{named} cycle lists in the preamble and use them with `|cycle list name|':
\begin{command}{\pgfplotscreateplotcyclelist\marg{name}\marg{list}}%
\end{command}
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{mylist}{%
	{blue,mark=*},
	{red,mark=square},
	{dashed,mark=o},
	{loosely dotted,mark=+},
	{brown!60!black,mark options={fill=brown!40},mark=otimes*}}
...
\begin{axis}[cycle list name=mylist]
	...
\end{axis}
\end{codeexample}

\subsubsection{Defining Cycle Lists: Input Format}
A |cycle list| is defined by key-value pairs of sorts |cycle list=|\marg{list} or by the equivalent macro outlined above, |\pgfplotscreateplotcyclelist|\marg{name}\marg{list}.

In this context, 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=*},
	{red,mark=square},
	{dashed,mark=o},
	{loosely dotted,mark=+},
	{brown!60!black,mark options={fill=brown!40},mark=otimes*}}
\end{codeexample}
Alternatively, one can terminate the inner lists (i.e.\ those for one single plot) with `|\\|':
\begin{codeexample}[code only]
\begin{axis}[cycle list={%
	blue,mark=*\\%
	red,mark=square\\%
	dashed,mark=o\\%
	loosely dotted,mark=+\\%
	brown!60!black,mark options={fill=brown!40},mark=otimes*\\%
}
]
...
\end{axis}
\end{codeexample}
In this case, the \emph{last} entry also needs a terminating `|\\|', but one can omit braces around the single entries.

\subsubsection{Manipulating Associations of Cycle Lists to Plots}
\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$).

	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]
\pgfplotsset{cycle list shift=3}
\addplot ....

\pgfplotsset{cycle list shift=-1}
\addplot ....
\end{codeexample}
	\paragraph{Special case:} If the result is negative, $i+n <0$, the list index $-(i+n)$ will be taken. For example, |cycle list shift=-10| and $i<10$ will result in list index $10-i$. Note that you can use |reverse legend| to reverse legends, so this feature is probably never needed.
\end{pgfplotskey}


\subsubsection{Defining Cycle Lists based on Color Maps}
In addition to defining |cycle list|s from scratch, \PGFPlots\ supports dedicated input definitions of |cycle list=|\meta{list} which allow to acquire values from an existing |colormap|. In this case, \meta{list} contains keys enclosed in square brackets:
\index{Colormap!Convert into Cycle list}

{%
\pgfplotsset{
	% ATTENTION: this is documented in this manual!
	cycle from colormap manual style/.style={
		x=3cm,y=10pt,ytick=\empty,
		colorbar style={x=,y=,ytick=\empty},
		point meta min=0,point meta max=1,
		stack plots=y,
		y dir=reverse,colorbar style={y dir=reverse},
		every axis plot/.style={line width=2pt},
		legend entries={0,...,20},
		legend pos=outer north east,
	}
}


The first syntax, \declareandlabel{of colormap}, allows to convert the colors of a |colormap| to a |cycle list|. It can be specified without argument by means of |cycle list={[of colormap]}| in order to take the value of the most recently assigned |colormap name| (i.e.\ the current |colormap|). It can also be specified as |cycle list={[of colormap=name]}| in which case it will use the specified |colormap name=name|. In both cases, the definition merely converts the colors as they are found in the colormap into the cycle list, i.e.\ there is no interpolation involved. Applying this to the default |colormap name=hot| which has $4$~colors results in the following example:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	colormap name=hot,colorbar,
	cycle list={[of colormap]},
	%
	cycle from colormap manual style,
	]
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
Note that since |hot| has $4$ colors, the |cycle list| also contains $4$ entries which are repeated every $4$ plots.

The second possibility is similar to |color of colormap|: it expects \declareandlabel{colors of colormap}|=|\marg{list} or |colors of colormap=|\marg{list}| of |\meta{colormap name}. This choice \emph{interpolates} colors and expects a \meta{list} of values in the range $[0,1000]$ where $0$ is the lowest element in the |colormap| and $1000$ is its highest element:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	colormap name=hot,colorbar,
	cycle list={
		[colors of colormap={0,100,...,1000}]},
	%
	cycle from colormap manual style,
	]
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
In this case, we specified $11$ colors and have $11$ plots. Clearly, interpolated colors are of limited use and are only applicable for special use-cases. Use only |cycle list|s of this sort if the |colormap| allows a suitable distinction of adjacent plot lines! Note that |colors of colormap| is quite similar to the related way to build colormaps based on existing colormaps as outlined in Section~\ref{sec:pgfplots:colormaps:based:on:others} on page~\pageref{sec:pgfplots:colormaps:based:on:others}.

A related choice is \declareandlabel{indices of colormap}|=|\marg{list}. As above, it accepts an optional `|of|' clause of the form |indices of colormap=|\marg{list}| of |\meta{colormap name}. The main argument is a list of indices $0\le N_i < N$ where $N$ is the number colors in the colormap definition (compare the documentation of |index of colormap|). Indices which are out of range are clipped to the nearest index. For example, |viridis| comes with $\pgfplotscolormapsizeof{viridis}$~elements and we can write
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	colormap name=viridis,colorbar,
	cycle list={
	 [indices of colormap={0,4,8,12,17} of viridis]},
	%
	cycle from colormap manual style,
	]
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
Note that `| of viridis|' is actually redundant as |viridis| was already selected in this case. In general, the syntax allows to select any (defined) colormap.  Note that |indices of colormap| is quite similar to the related way to build colormaps based on existing colormaps as outlined in Section~\ref{sec:pgfplots:colormaps:based:on:others} on page~\pageref{sec:pgfplots:colormaps:based:on:others}.

A further related choice is \declareandlabel{const colors of colormap}|=|\marg{list}. It is about the same as |colors of colormap|, except that it uses |const color of colormap| as color specification, i.e.\ the strategy |colormap access=piecewise constant|.

Note that all these special lists are valid arguments for |\pgfplotscreateplotcyclelist| and can also appear as sub-lists in |cycle multi list| and its variants.

Since creating a |cycle list| from a |colormap| necessarily results in plots without markers and line style variations, it makes sense to combine the result with |cycle multiindex* list|, i.e.\ to join two existing lists. The following example joins a pure color list with markers:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    colormap name=hot,colorbar,
    cycle multiindex* list={
        [colors of colormap={0,100,...,1000}]\nextlist
		mark list\nextlist
	},
    %
    cycle from colormap manual style,
    ]
\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)};
\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)};
\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)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent Please refer to the next subsection for details about |cycle multiindex* list|.

Note that the preceding examples all use the following style.
\begin{stylekey}{/pgfplots/cycle from colormap manual style}
	A style defined in this manual. It has the value
\begin{codeexample}[code only]
\pgfplotsset{
	cycle from colormap manual style/.style={
		x=3cm,y=10pt,ytick=\empty,
		colorbar style={x=,y=,ytick=\empty},
		point meta min=0,point meta max=1,
		stack plots=y,
		y dir=reverse,colorbar style={y dir=reverse},
		every axis plot/.style={line width=2pt},
		legend entries={0,...,20},
		legend pos=outer north east,
	}
}
\end{codeexample}
\end{stylekey}

}%


\paragraph{Remark:} It is possible to call |\pgfplotsset{cycle list=|\marg{a list}|}| or |cycle list name| \emph{between} plots. Such a setting remains effective until the end of the current \TeX\ group (that means curly braces). Every |\addplot| command queries the |cycle list| using the plot index; it doesn't hurt if |cycle list|s have changed in the meantime.
\end{pgfplotskeylist}

\begin{pgfplotskey}{cycle list/.define=\marg{name}{list}}
	A command which merely calls |\pgfplotscreateplotcyclelist|\marg{name}\marg{list} without actually selecting it as the current list.

	Note that \PGFPlots\ uses this to implement its |cycle list| key as follows:
\begin{codeexample}[code only]
\pgfplotsset{
	cycle list/.style={%
		cycle list/.define={@internal@}{#1},%
		cycle list name={@internal@}%
	},
}
\end{codeexample}
	
\end{pgfplotskey}

\subsubsection{Building Block to Combine Different Cycle Lists}
The following keys allow to combined different |cycle list|s in order to build more complex ones.

\begin{pgfplotskey}{cycle multi list=\meta{list 1}\texttt{\textbackslash nextlist}\meta{list 2}\texttt{\textbackslash nextlist}$\dotsb$}
	This is one of two ways to employ more than one |cycle list| in order to determine the plot style (see also |cycle multiindex list| for the other one). This is probably best explained using an example:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	cycle multi list={
	  red,blue\nextlist
	  solid,{dotted,mark options={solid}}\nextlist
	  mark=*,mark=x,mark=o
	},
	samples=3,
	legend entries={0,...,20},
	legend pos=outer north east
]
	\addplot {x};
	\addplot {x-1};
	\addplot {x-2};
	\addplot {x-3};
	\addplot {x-4};
	\addplot {x-5};
	\addplot {x-6};
	\addplot {x-7};
	\addplot {x-8};
	\addplot {x-9};
	\addplot {x-10};
	\addplot {x-11};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The provided |cycle multi list| consists of three lists. The style for a single plot is made up using elements of each of the three lists: the first plot has style |red,solid,mark=*|, the second has |red,solid,mark=x|, the third has |red,solid,mark=o|. The fourth plot restarts the third list and uses the next one of list $2$: it has |red,dotted,mark options={solid},mark=*| and so on.

	The last list will always be advanced for a new plot. The list before the last (in our case the second list) will be advanced after the last one has been reset. In other words: |cycle multi list| allows a composition of different |cycle list| in a lexicographical way\footnote{For those who prefer formulas: The plot with index $0 \le i < N$ will use cycle list offsets $i_0,i_1,\dotsc,i_k$, $0 \le i_m < N_m$ where $k$ is the number of arguments provided to \texttt{cycle multi list} and $N_m$ is the number of elements in the $m$th cycle list. The offsets $i_m$ are computed in a loop {\ttfamily \{ int tmp=i;  for( int m=k-1; m>=0; m=m-1 ) \{ i\_m = tmp\%N\_m; tmp = tmp/N\_m; \}\}}.}.

	The argument for |cycle multi list| is a sequence of arguments as they would have been provided for |cycle list|, separated by \declareandlabel{\nextlist}. In addition to providing a new cycle list, the \meta{list $i$} elements can also denote |cycle list name| values (including the special |auto| cycle list which is the most recently assigned |cycle list| or |cycle list name|). The final |\nextlist| is optional.

	The list in our example above could have been written as
\begin{codeexample}[code only]
\begin{axis}[
	cycle multi list={
		red\\blue\\\nextlist
		solid\\dotted,mark options={solid}\\\nextlist
		mark=*\\mark=x\\mark=o\\
	}]
\end{codeexample}
\noindent as well (note the terminating |\\| commands!).

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	title={Cycle color between successive plots, then marks},
	cycle multi list={
		mark list\nextlist
		blue,red%
	},
	samples=3,
	legend entries={0,...,20},
	legend pos=outer north east
]
	\addplot {x};
	\addplot {x-1};
	\addplot {x-2};
	\addplot {x-3};
	\addplot {x-4};
	\addplot {x-5};
	\addplot {x-6};
	\addplot {x-7};
	\addplot {x-8};
	\addplot {x-9};
	\addplot {x-10};
	\addplot {x-11};
\end{axis}
\end{tikzpicture}
\end{codeexample}


	\paragraph{Using Sub--Lists} The \meta{list $i$} entry can also contain just the first $n$ elements of an already known cycle list name using the syntax |[|\meta{number}| of]|\meta{cycle list name}. For example |[2 of]mark list| will use the first $2$ elements of |mark list|:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	title={Cycle 2 marks between successive plots, then colors},
	cycle multi list={%
		color list\nextlist
		[2 of]mark list
	},
	samples=3,
	legend entries={0,...,20},
	legend pos=outer north east
]
	\addplot {x};
	\addplot {x-1};
	\addplot {x-2};
	\addplot {x-3};
	\addplot {x-4};
	\addplot {x-5};
	\addplot {x-6};
	\addplot {x-7};
	\addplot {x-8};
	\addplot {x-9};
	\addplot {x-10};
	\addplot {x-11};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}

\begin{pgfplotskey}{cycle multiindex list=\meta{list 1}\texttt{\textbackslash nextlist}\meta{list 2}\texttt{\textbackslash nextlist}$\dotsb$}
	This is one of two ways to employ more than one |cycle list| in order to determine the plot style (see also |cycle multi list| for the other one). The difference between the two choices is how the list index is mapped into the sub lists. Let us start with our example:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    cycle multiindex list={
      red,blue,teal\nextlist
      solid\\dotted,mark options={solid}\\only marks\\\nextlist
      mark=*,mark=x,mark=oplus\nextlist
    },
    samples=3,
    legend entries={0,...,20},
    legend pos=outer north east
]
    \addplot {x};
    \addplot {x-1};
    \addplot {x-2};
    \addplot {x-3};
    \addplot {x-4};
    \addplot {x-5};
    \addplot {x-6};
    \addplot {x-7};
    \addplot {x-8};
    \addplot {x-9};
    \addplot {x-10};
    \addplot {x-11};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The provided |cycle multiindex list| consists of three lists. The style for a single plot is made up using elements of each of the three lists: the first plot has style |red,solid,mark=*|, the second has |blue,dotted,mark options={solid},mark=x|, the third has |teal,only marks,oplus|. The fourth plot restarts all lists and uses the same as the first plot, i.e.\ |red,solid,mark=*|. 
	
	Note that the second list uses the list-separator `|\\|' which requires a final terminator as defined for |cycle list|.

	Thus, this style uses \emph{the same} index into every list (a ``multi index''). Consequently, it has considerably less different choices than |cycle multi list| (which results in all possible variations), but its combination method addresses different use-cases.
	
	The argument for |cycle multiindex list| has the very same format as the one for |cycle multi list|, including the special |[2 of]mark list| syntax and providing other cycle lists by name:

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	title={Same index of each input list},
    cycle multiindex list={
        [3 of]mark list\nextlist
        blue,red\nextlist
		linestyles\nextlist
    },
    samples=3,
    legend entries={0,...,20},
    legend pos=outer north east
]
    \addplot {x};
    \addplot {x-1};
    \addplot {x-2};
    \addplot {x-3};
    \addplot {x-4};
    \addplot {x-5};
    \addplot {x-6};
    \addplot {x-7};
    \addplot {x-8};
    \addplot {x-9};
    \addplot {x-10};
    \addplot {x-11};
\end{axis}
\end{tikzpicture}
\end{codeexample}

	Note that |cycle multiindex list| accepts lists of different sizes. The size of a |cycle multiindex list| is the size of the \emph{largest} input list, all smaller input lists are padded with empty option lists. That is why the previous example uses the color |black| for every third plot: there is no color in the second list, and omitting the color results in |black|. As soon as the last item of the largest sub-list has been used, the list is restarted.
\end{pgfplotskey}

\begin{pgfplotskey}{cycle multiindex* list=\meta{list 1}\texttt{\textbackslash nextlist}\meta{list 2}\texttt{\textbackslash nextlist}$\dotsb$}
	A variant of |cycle multiindex list| which behaves in the same way -- except for sub-lists of different sizes.

	As documented above, the unstarred version |cycle multiindex list| pads missing entries with \emph{empty} options lists until all list elements have the same size.

	The starred key |cycle multiindex* list| restarts sub-lists independently whenever they reach their end:

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	title={Same index of each input list, lists restarted},
    cycle multiindex* list={
        [3 of]mark list\nextlist
        blue,red\nextlist
		linestyles\nextlist
    },
    samples=3,
    legend entries={0,...,20},
    legend pos=outer north east
]
    \addplot {x};
    \addplot {x-1};
    \addplot {x-2};
    \addplot {x-3};
    \addplot {x-4};
    \addplot {x-5};
    \addplot {x-6};
    \addplot {x-7};
    \addplot {x-8};
    \addplot {x-9};
    \addplot {x-10};
    \addplot {x-11};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	This is the very same example as documented for the unstarred variant |cycle multiindex list|. However, the second sub-list has fewer elements -- and while the unstarred variant resulted in |black|, the starred variant restarts the second sub-list as soon as its two existing colors are consumed.

	This style allows to concatenate lists in complex ways:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	title={Same index of each input list},
    cycle multiindex* list={
        red,blue,teal,brown\nextlist
        mark=*,mark=square*,mark=triangle*\nextlist
		dashed,every mark/.append style={
			solid,draw=.!50!black,fill=.,}\\
		\nextlist
    },
    samples=3,
    legend entries={0,...,20},
    legend pos=outer north east
]
    \addplot {x};
    \addplot {x-1};
    \addplot {x-2};
    \addplot {x-3};
    \addplot {x-4};
    \addplot {x-5};
    \addplot {x-6};
    \addplot {x-7};
    \addplot {x-8};
    \addplot {x-9};
    \addplot {x-10};
    \addplot {x-11};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	We see that the four different colors appear periodically as expected. We also see the three different markers with their own period (which restarts every fourth plot as expected). But the third sub-list contains just one element as we can see by its separator character `|\\|' which appears just once at the end of the list! Consequently, this list is restarted for \emph{every} plot such that every plot receives its arguments.
\end{pgfplotskey}

\subsection{Axis Background}
\begin{pgfplotskey}{axis background (initially empty)}
	This is a style to configure the appearance of the axis as such. It can be defined and/or changed using the |axis background/.style=|\marg{options} method. A background path will be generated with \meta{options}, which may contain fill colors or shadings.

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		axis background/.style={fill=blue!10}]

	\addplot3[surf,y domain=0:1] 
		{sin(deg(x)) * y*(1-y)};
		
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	Please note that legends are filled with white in the default configuration.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{semilogyaxis}[
		axis background/.style={
			shade,top color=gray,bottom color=white},
		legend style={fill=white}]

	\addplot {exp(-x)};
	\addplot {exp(-4*x)};
	\legend{$e^{-x}$,$e^{-4x}$}
	\end{semilogyaxis}
\end{tikzpicture}
\end{codeexample}
	Details about |fill| and |shade| can be found in the \Tikz\ manual, \cite{tikz}.
\end{pgfplotskey}


\section{Providing Color Data - Point Meta}
\label{pgfplots:point:meta}
\PGFPlots\ provides features which modify plots depending on a special coordinate, the ``point meta data''. For example, scatter plots may vary marker colors, size or appearance depending on this special data. Surface and mesh plots are another example: here, the color of a surface patch (or mesh part) depends on ``point meta''. The ``meta data'' of a node is not the position (which is given as $(x,y)$ or $(x,y,z)$). It is ``some information'' about that node; you could say: it is a specific property of the node. This is commonly called ``meta data''. 

\subsection{Point Meta Overview}
In \PGFPlots, every node has its coordinate \emph{and} its meta data. Thus, two--dimensional plots have three values: $x$, $y$, and the |point meta| data. Three--dimensional plots have four values for each coordinate: $x$, $y$, $z$, and the |point meta|. 

In many cases, |point meta| is interpreted to be color data. To be more precise: it is interpreted to be \emph{scalar} color data which is mapped into the |colormap| (more about this approach in the next paragraphs). However, |point meta| can be anything. Often, it is a single number as in the case of color data. That number is mapped linearly to the interval $[0,1000]$ such that $0$ corresponds to the smallest encountered value and $1000$ corresponds to the largest encountered scalar value. The mapped value is available as |\pgfplotspointmetatransformed|. This special value allows to define some property of the plot: it can be the color (together with |colormap|). It can also be the |line width| in a |mesh| plot (more precisely: the |line width| could be defined to depend on the transformed meta data). An example for this approach is on page~\pageref{pgfplots:example:pointmeta:quiver} where a |quiver| plot's arrow line with depends on |\pgfplotspointmetatransformed|. The value can also be used to define |mark size| as in the example for |scatter/@pre marker code| on page~\pageref{pgfplots:example:pointmeta:scatter}. However, |point meta| data does not necessarily need to be a number. It can be a text label (any text that you like). This is used by |nodes near coords|, for example. It could also contain a tuple like RGB color information (compare |mesh/color input=explicit|). Thus, |point meta| is really some abstract information about individual coordinates.

Note that there is only \emph{one} |point meta| per point. See the key |visualization depends on| if you need more than one meta data value per coordinate. 

The common idea is to tell \PGFPlots\ how to get the meta data. It is not necessary to provide data explicitly -- in many cases, the data which is used to color |surf|ace patches or |mark|er colors is the plot's $y$ or $z$ coordinate. The method used to tell \PGFPlots\ where to find ``point meta data'' is the |point meta| key. 

The most common use-case of |point meta| is color information: if the point meta data is in the interval $[m_{\text{min}},m_{\text{max}}]$, the point meta coordinate for the smallest encountered value $m = m_{\text{min}}$ will get the lowest color provided by the |colormap| while the largest encountered value $m=m_{\text{max}}$ will get the highest color provided by the |colormap|. As already mentioned, this is accomplished using |\pgfplotspointmetatransformed| $\in [0,1000]$ (per convention). Any coordinate between the smallest and largest values will be mapped linearly: for example, the mean $m = 1/2 (m_{\text{max}} + m_{\text{min}})$ will get the middle color of the color map (it will have |\pgfplotspointmetatransformed| $=500$). This is why ``point meta'' is sometimes called ``color data'' in this manual.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar]
		\addplot[mesh,point meta=y,thick] {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\subsection{User Input Format for Point Meta}

\begin{pgfplotskey}{point meta=\mchoice{none,\meta{expression},x,y,z,f(x),explicit,explicit symbolic} (initially none)}
	\label{pgfplots:pointmeta}
	The |point meta| key tells \PGFPlots\ where to get the special point meta data. Please note that |point meta| and |scatter src| is actually the same -- |scatter src| is an alias for |point meta|. Thus, the summary provided for |scatter src| on page~\pageref{pgfplots:scatter:src} covers the same topics. However, the main reference for |point meta| is here.
	
	\begin{description}
		\item[\declaretext{none}] The initial choice |none| disables point meta data, resulting in no computational work. Any other choice will activate the computation of upper and lower ranges for point meta data, i.e.\ the computation of $[m_{\text{min}},m_{\text{max}}]$. 

		\item[\declaretext{x}] The choice |x| uses the already available $x$ coordinates as point meta data. This does always refer to the \emph{final} $x$ coordinates after any user transformations, logarithms, stacked plot computations etc.\ have been applied. Consider using |rawx| if you need the unprocessed coordinate value here.

		\item[\declaretext{y}]
		\item[\declaretext{z}]
			 The choices |y| and |z| are similar: they use the $y$ or $z$ coordinates respectively as point meta data. Consequently, these three choices do \emph{not} need any extra data. As for |x|, there are math constants |rawy| and |rawz| which yield the unprocessed $y$ and $z$ value, respectively.

		\item[\declaretext{f(x)}] This will use the last available coordinate, in other words: it is the same as |y| for two dimensional plots and |z| for three dimensional ones.

		\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:
\begin{codeexample}[code only]
% for 'coordinates':
% provide color data explicitly using [<data>]
% behind coordinates:
\addplot+[point meta=explicit]
	coordinates {
		(0,0) [1.0e10]
		(1,2) [1.1e10]
		(2,3) [1.2e10]
		(3,4) [1.3e10]
		% ...
	};
\end{codeexample}

\begin{codeexample}[code only]
% for 'table':
% Assumes a datafile.dat like
% xcolname  ycolname    colordata
% 0         0           0.001
% 1         2           0.3
% 2         2.1         0.4
% 3         3           0.5
% ...
% the file may have more columns.
\addplot+[point meta=explicit]
	table[x=xcolname,y=ycolname,meta=colordata] 
		{datafile.dat};
% or, equivalently (perhaps a little bit slower):
\addplot+[point meta=\thisrow{colordata}]
	table[x=xcolname,y=ycolname] 
		{datafile.dat};
\end{codeexample}

\begin{codeexample}[code only]
% for 'file':
% Assumes a datafile.dat like
% 0         0           0.001
% 1         2           0.3
% 2         2.1         0.4
% 3         3           0.5
% ...
% the first three columns will be used here as x,y and meta,
% resp.
\addplot+[point meta=explicit]
	file {datafile.dat};
\end{codeexample}

\begin{codeexample}[code only]
% 'table' using expressions which may depend on all
% columns:
% Assumes a datafile.dat like
% xcolname  ycolname    anything    othercol
% 0         0           4           15
% 1         2           5           20
% 2         2.1         8           30
% 3         3           42          40
% ...
% the file may have more columns.
\addplot+[point meta={0.5*(\thisrow{anything} + sqrt(\thisrow{othercol}))}]
	table[x=xcolname,y=ycolname]
		{datafile.dat};
\end{codeexample}
		Thus, there are several methods to provide point meta (color data). The key for the choice |explicit| is that some data is provided explicitly -- although |point meta| does not know how. The data is expected to be of numerical type and is mapped linearly into the range $[0,1000]$ (maybe for use in the current color map).

		\item[\declaretext{explicit symbolic}] The choice |explicit symbolic| is very similar to |explicit| in that it expects extra data by the coordinate input routines. However, |explicit symbolic| does not necessarily expect numerical data: you can provide any sort of symbols. One might provide a set of styles, one for each class in a scatter plot. This is implemented using |scatter/classes|, see page~\pageref{pgfplots:scatterclasses}. Input data is provided in the same fashion as mentioned above for the choice |explicit|. 
		
		This choice is usedful for |nodes near coords| with textual labels (see page~\pageref{pgfplots:example:pointmeta:nodesnearcoords}) and for |surf|ace plots with explicit color (see |mesh/color input=explicit| for details).

		\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). If coordinates are provided using |\addplot table|, the macro |\thisrow|\marg{colname} is particularly useful as it allows to access the value of the provided \meta{colname} of the ``current'' row. 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{%
		 In rare circumstances, it might be interesting to apply a math expression to another source of point meta (one of the other choices. To this end, the \meta{expression} is checked after the other possible choices have already been evaluated. In other words, the statement \texttt{point meta=explicit, point meta=meta*meta+3} will evaluate the expression with |meta| set to whatever data has been provided explicitly.}.
		If used together with |plot table|, you may also access other table columns (for example with |\thisrow|\marg{colname}).

		\item[\normalfont\declaretext{TeX code}\texttt{=}\meta{code}] A rather low level choice which allows to provide \TeX\ \meta{code} to compute a numerical value. The \meta{code} should define the macro |\pgfplotspointmeta|. It is evaluated in a locally scoped environment (it's local variables are freed afterwards). It may depend on the same values as described for \meta{expression} above, especially on |\thisrow|\marg{colname} for table input.

		Note that the math parser will be configured to use the |fpu| at this time, so |\pgfmathparse| yields floats. 

		Note that you need an extra pair of braces to provide this key, i.e.
		
		|point meta={TeX code=|\marg{code}|}|.

		\item[\normalfont\declaretext{TeX code symbolic}\texttt{=}\meta{code}] Just as |TeX code|, you can provide \meta{code} which defines the macro |\pgfplotspointmeta|, but the result is not interpreted as a number. It is like the |explicit symbolic| choice.

		Note that you need an extra pair of braces to provide this key, i.e.
		
		|point meta={TeX code symbolic=|\marg{code}|}|.
		
		\item[\normalfont\declaretext{symbolic}\texttt{=}\meta{symbol}] A choice which accepts some arbitrary \meta{symbol} which is used for every coordinate. As |explicit symbolic| and |TeX code symbolic|, this choice yields symbolic representations, i.e.\ it is kept as--is without mapping the result.

		The difference to |explicit symbolic| is that \meta{symbol} is a common symbol for all points whereas |explicit symbolic| expects the input data stream (like a table) to provide individual symbols.

		The different to |TeX code symbolic| is marginal: |symbolic| is actually the same as 

		|point meta/TeX code symbolic={\def\pgfplotspointmeta|\marg{symbol}|}|.

		A use-case for |symbolic| is |mesh/color input=explicit mathparse|, see the documentation there-in.

		Note that you need an extra pair of braces to provide this key, i.e.
		
		|point meta={symbolic=|\marg{symbol}|}|.
	\end{description}

	As already mentioned, a main application of point meta data is to determine (marker/face/edge) colors using a linear map into the range $[0,1000]$ (maybe for use in the current color map). This map works as follows: it is a function
	\[ \phi\colon [m_{\text{min}},m_{\text{max}}] \to [0,1000] \]
	with
	\[ \phi(m) = \frac{m - m_{\text{min}}} {1000} \]
	such that $\phi(m_{\text{min}}) = 0$ and $\phi(m_{\text{max}})=1000$. The value $1000$ is -- per convention -- the upper limit of all color maps. Now, if a coordinate (or edge/face) has the point meta data $m$, its color will be determined using $\phi(m)$: it is the color at $\phi(m)$\textperthousand\ of the current color map.

	This transformation depends on the interval $[m_{\text{min}},m_{\text{max}}]$ which, in turn, can be modified using the keys |point meta rel|, |point meta min| and |point meta max| described below.

	The untransformed point meta data is available in the macro \declareandlabel{\pgfplotspointmeta} (only in the correct context, for example the scatter plot styles or the |scatter/@pre marker code| interface). This macro contains a low level floating point number (unless it is non-parsed string data). The transformed data will be available in the macro \declareandlabel{\pgfplotspointmetatransformed} and is in fixed point representation. It is expected to be in the range $[0,1000]$.

\end{pgfplotskey}

\begin{pgfplotskey}{set point meta if empty=\marg{point meta source}}
	Sets |point meta=|\meta{point meta source}, but only if |point meta=none| currently. This is used for |scatter|, |mesh| and |surf| with |set point meta if empty=f(x)|.
\end{pgfplotskey}

\subsection{Mapping Point Meta and Color Maps}

	As already explained in the documentation for |point meta|, one application for point meta data is to determine colors using the current color map and a linear map from point meta data into the current color map. This subsection shows keys to control this mapping.

	The plot handlers |surf|, |mesh|, |patch|, |scatter|, |contour prepared|, and some related ones all make use of mapped colors. To this end, the value provided by |point meta| is processed as follows:
	\begin{itemize}
		\item First, all encountered values are collected (during |\addplot|) and the largest and smallest value, $m_{\text{max}}$ and $m_{\text{min}}$, are computed. The value is stored in |\pgfplotspointmeta|.
		\item Second, every encountered value $m$ is mapped to $[0,1000]$ using a linear map: $m_{\text{min}} \to 0$; $m_{\text{max}}\to 1000$, and all values in-between are mapped linearly. This value is stored (and available) in the \TeX\ macro |\pgfplotspointmetatransformed| (but not before |\end{axis}|).
		\item Finally, the mapped value |\pgfplotspointmetatransformed| is mapped into the current |colormap|. The resulting color is called \declareandlabel{mapped color}.
	\end{itemize}
	The plot handlers, in turn, use |mapped color| in order to render their colors (often combined with color mixins like |mapped color!80!black|).

\begin{pgfplotskey}{point meta rel=\mchoice{axis wide,per plot} (initially axis wide)}
	The key |point meta rel| configures whether the interval of all point meta coordinates, $[m_{\text{min}},m_{\text{max}}]$ is computed as maximum over all plots in the complete axis (the choice \declaretext{axis wide}) or only for one particular plot (the choice \declaretext{per plot}).

\message{Overfull hbox is ok.}%
\begin{codeexample}[]
\begin{tikzpicture}
   \begin{axis}[
      title=Axis wide color mapping,
      colorbar,
      samples=50,point meta rel=axis wide,
	  point meta=y]

      \addplot[mesh,thick] {sin(deg(x))};
      \addplot[mesh,thick] {3*tanh(x)};
   \end{axis}
\end{tikzpicture}
~
\begin{tikzpicture}
   \begin{axis}[
      title=Per Plot color mapping,
      colorbar,
      samples=50,
	  point meta rel=per plot,
	  point meta=y]

      \addplot[mesh,thick] {sin(deg(x))};
      \addplot[mesh,thick] {3*tanh(x)};
   \end{axis}
\end{tikzpicture}
\end{codeexample}

	Note that a |colorbar| will still use the |axis wide| point meta limits. Consider the |colorbar source| key if you want the color data limits of a \emph{particular} plot for your color bar. The |point meta rel| key configures how point meta maps to colors in the |colormap|.
\end{pgfplotskey}

\begin{pgfplotskeylist}{point meta min=\marg{number},point meta max=\marg{number}}
	These keys allow to define the range required for the linear map of point meta data into the range $[0,1000]$ (for example, for current maps) explicitly. This is necessary if the same mapping shall be used for more than one axis.

	\paragraph{Remarks about special cases:}
	\begin{itemize}
		\item It is possible to provide limits partially; in this case, only the missing limit will be computed.
		\item If point meta data falls outside of these limits, the linear transformation is still well defined which is acceptable (unless the interval is of zero length). However, color data can't be outside of these limits, so color bars perform a truncation.
		\item This key can be provided for single plots as well as for the complete axis (or for both).
		\item If meta limits are provided for a single plot, these limits may also contribute to the axis wide meta interval.
	\end{itemize}
\end{pgfplotskeylist}

\begin{pgfplotskey}{colormap access=\mchoice{map,direct,const,\\piecewise constant,piecewise const,piecewise linear} (initially map)}
	This key configures how point meta data is used to determine colors from a color map.
	
	\subsubsection{Mapping Point Meta using Piecewise Constant Interpolation}
	The initial configuration \declaretext{map} performs the linear mapping operation explained above in all detail.
	
	\subsubsection{Using Colormaps as Indexed Color Space (Palette)}
	The choice \declaretext{direct} does not perform any transformation; it interpretes the value of |point meta| as integer indices into the current color map. If a number is no integer, it will be truncated by throwing away any fraction parts of the number. Consequently, it is quite similar to |index of colormap|.\index{index of colormap}

\def\showcolorandname#1{%
	\showcolor{#1}~\pgfmanualpdfref{#1}{\texttt{#1}}%
}%
\def\showcolor#1{%
	\tikz \draw[black,fill={#1}] (0,0) rectangle (1em,0.6em);%
}%
%
	Suppose we have the color definitions
	\showcolorandname{RdPu-K}, 
	\showcolorandname{RdPu-I}, 
	\showcolorandname{RdPu-G}, 
	\showcolorandname{RdPu-E}, and
	\showcolorandname{RdPu-B} (which are actually taken from |\usetikzlibrary{colorbrewer}|).

	We will use these colors in order to define a |colormap|:

\begin{codeexample}[]
% requires \usetikzlibrary{colorbrewer}
\begin{tikzpicture}
\begin{axis}[
	colormap={brewer}{
		color=(RdPu-B) color=(RdPu-E) 
		color=(RdPu-G) color=(RdPu-I) 
		color=(RdPu-K)},
	enlargelimits=false,
	colorbar as palette,
]
\addplot[matrix plot,
	nodes near coords,mark=*,
	point meta=explicit,
	colormap access=direct,	
]
coordinates {
(0,0) [0] (1,0) [1] (2,0) [2] (3,0) [NaN]

(0,1) [3] (1,1) [4] (2,1) [5] (3,1) [99]

(0,2) [3.5] (1,2) [-1] (2,2) [2.99] (3,2) [3]
};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	The example has a $3\times 4$ matrix, each with explicitly provided values of |point meta|. The first point has a |point meta| value of~$0$ and uses the first color of the |colormap| (|RdPu-B|, \showcolor{RdPu-B}). The second point has value~$1$ and uses the second color, |RdPu-E| \showcolor{RdPu-E}, and so on. Note that |NaN| is interpreted as `hole' in the matrix and is left empty (you see the background color here). Note furthermore that coordinate |(1,2) [-1]| is mapped to the first color since values outside of the allowed range are automatically clipped to the next correct color. The same holds for the point with |[99]|: it is mapped to the last available color~\showcolor{RdPu-K}. Finally, the point with |[2.99]| is mapped to index $2$~(\showcolor{RdPu-G}) since |colormap access=direct| truncates to the next integer index.

\begin{pgfplotskey}{colorbar as palette}
	The example above makes use of |colorbar as palette|, a dedicated style useful for such palette-type applications.

	It is defined as
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar as palette/.style={
		colorbar sampled={
			surf,
			colormap access=direct,
			shader=flat corner,
			samples=\pgfplotscolormapsizeof
			{\pgfkeysvalueof{/pgfplots/colormap name}}+1,
		},
		colorbar style={
			point meta min=0,
			point meta max=\pgfplotscolormapsizeof
			{\pgfkeysvalueof{/pgfplots/colormap name}},
		}}}
\end{codeexample}
	The idea is to show only the colors of the ``palette'', i.e.\ without interpolating values of the |colormap|. Furthermore, it is supposed to show all available colors.

	See also the closely related (but more general) |colorbar as legend|.
\end{pgfplotskey}

	Note that |colormap access=direct| changes the way how |point meta| is translated to colors. However, it does \emph{not affect} |shader|. In other words, it is perfectly sane to use |shader=interp| or |shader=flat mean|. This, however, will interpolate the colors resulting from |colormap access=direct|! Our example above uses |shader=flat corner| which results in no color interpolation at all.

	The choice |colormap access=direct| is actually like a color palette for images with indexed colorspaces: suppose we use the famous ``Lena'' image~\cite{lena}, downsample it to $128\times 128$, and export it to coordinates of the form
\begin{codeexample}[code only]
1 1 194
1 2 194
1 3 170
1 4 193
1 5 188
1 6 188
...
\end{codeexample}
	with an indexed colorspace. Furthermore, we import its color palette as \PGFPlots\ |colormap|. To this end, a small Matlab script serves as utility to convert a |tiff| image to coordinates:\footnote{Also see Section~\ref{sec:pgfplots:import:matlab}, ``Importing Mesh Data From Matlab To PGFPlots'' on page~\pageref{sec:pgfplots:import:matlab}}
\begin{codeexample}[code only]
[Z,cm] = imread('4.2.04_128.tiff');
[X,Y]=meshgrid(1:size(Z,1), 1:size(Z,2));
data = [ X(:) Y(:) Z(:) ];
fid = fopen('lena.dat', 'w');
fprintf(fid, "%d %d %d\n", data');
fclose(fid);

fid = fopen('lena_cm.tex', 'w');
fprintf(fid, "\\pgfplotsset{colormap={lena palette}{\n");
fprintf(fid, "rgb=(%f,%f,%f)\n", cm');
fprintf(fid, "}}\n");
fclose(fid);
\end{codeexample}
	This allows us to import the graphics into \PGFPlots\ as |matrix plot|:
\tikzset{external/figure name/.add={}{lena_}}%
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	% load and activate the CM:
	\input lena_cm.tex
	\begin{axis}[view={0}{90},axis equal]
	\addplot3[matrix plot,
		colormap access=direct,
		mesh/rows=128,
		mesh/ordering=colwise,
	]
		table {lena.dat};	
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The files |lena_cm.tex| and |lena.dat| are shipped with \PGFPlots\ and can be downloaded from CTAN. The keys to decode the table data into a |mesh| are specific to the Matlab export format of our script.
	
	Note that rendering images from coordinates is considerably less efficient than |\includegraphics| in terms of
\begin{itemize} 
	\item computational time required by \PGFPlots, 
\item space consumption in the resulting |pdf| document,
\item and time to render the resulting |pdf| in the viewer(s).
\end{itemize}
	Depending on the use-case, \verbpdfref{\addplot graphics} may help to reduce typesetting times.

	\paragraph{Some more details:}
	\begin{itemize}
		\item If there are $m$ colors in the color map and the color data falls outside of $[0,m-1]$, it will be pruned to either the first or the last color.
		\item If color data is a real number, it will be truncated to the next smaller integer.
		\item If |colormap access=direct| is combined with a |shader|$\neq$|flat corner|, color interpolation takes place. However, the color interpolation is not carried out in terms of the scalar |point meta| (as would have been done for |colormap access=map|). Instead, it is carried out on the \emph{resulting} colors in their own colorspace. 

		\item Note that |patch refines| or |patch to triangles| is unsupported in this context (at the time of this writing, it will interpolate the color indices, resulting in badly defined behavior).

	\end{itemize}

	See also the related keys |color of colormap| and |index of colormap|.

	
	The choice |colormap access=|\declaretext{piecewise linear} is an alias for |colormap access=map|. It is related to |color of colormap|.\index{color of colormap}

	\subsubsection{Mapping Point Meta using Piecewise Constant Interpolation}
	
	\paragraph{Beware: Viewer Limitations} The following paragraph makes uses of \textsc{pdf} features which are unsupported by some free viewers (including |pdf.js| and |evince|). Please resort to a suitable viewer if you see unexpected results.

	The choice |colormap access=|\declaretext{piecewise constant} is very similar to |colormap access=map|: it accepts the same |point meta| values as input, maps them linearly into $[0,1000]$ and uses the first color of the |colormap| if the value of |point meta| is |point meta min| and the last color of the |colormap| if the value of |point meta| is |point meta max|. However, values of |point meta| which fall \emph{between} two |colormap| entries are interpolated using \emph{piecewise constant} interpolation, i.e.\ just like |const plot|: the interpolated color resembles the value of the \emph{first} color of the interval. As a consequence, the result contains at most  as many colors as the |colormap| provides:
\begin{codeexample}[]
% requires \usepgfplotslibrary{colorbrewer}
\begin{tikzpicture}
\begin{axis}[
	colormap access=piecewise constant,
	colormap/RdPu-6,
	%
	colorbar horizontal,
]
\addplot3[
	surf,
] {x*y};	
\end{axis}
\end{tikzpicture}
\end{codeexample}
	The choice |colormap access=piecewise constant| is compatible with all available |shader|s, but its best results are possible using |shader=interp| as this will avoid rectangular artifacts at mesh boundaries.
\begin{codeexample}[]
% requires \usepgfplotslibrary{colorbrewer}
\begin{tikzpicture}
\begin{axis}[
	colormap access=piecewise constant,
	colormap/RdPu-6,
	%
	colorbar horizontal,
]
\addplot3[
	surf,
	shader=interp,
] {x*y};	
\end{axis}
\end{tikzpicture}
\end{codeexample}

	The choice |colormap access=piecewise constant| requires |colormap|s with a suitable number of colors. This is quite different to |colormap access=map| (or |piecewise linear|) where the actual number of colors in the |colormap| cannot be seen in the resulting plot. In order to get the desired effects, one may need the same |colormap| with a different number of samples. To this end, one can make use of the special |colormap| syntax which is based on |samples of colormap| and its variants:

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    colormap access=piecewise constant,
	colormap={my sampled version of viridis}{
		samples of colormap=(10 of viridis)},
    %
	colorbar horizontal,
]
\addplot3[
    surf,
    shader=interp,
] {x*y};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	The example takes the existing |colormap name=viridis| and chooses $10$ samples of it. The result is called |my sampled version of viridis| and is used as ``current colormap''. Details about this process can be read in Section~\ref{sec:pgfplots:colormaps:based:on:others} on page~\pageref{sec:pgfplots:colormaps:based:on:others}.

	\paragraph{See also} the plot handler |contour filled| which is based on such a visualization scheme.

	The strategy which determines colors in this context is also available as |const color of colormap|.\index{const color of colormap}.

	The choices \declareandlabel{piecewise const} and \declaretext{const} are aliases for |piecewise constant|.
\end{pgfplotskey}

