Manual for Package pgfplots
2D/3D Plots in LATeX, Version 1.18.1
http://sourceforge.net/projects/pgfplots

\addplot3[options] input data trailing path commands; ¶

The \addplot3 command is the main interface for any three dimensional plot. It works in the same way as its two dimensional variant \addplot which has been described in all detail in Section 4.3.

The \addplot3 command accepts the same input methods as the \addplot variant, including expression plotting, coordinates, files and tables. However, a third coordinate is necessary for each of these methods which is usually straightforward and is explained in all detail in the following.

Furthermore, \addplot3 has a way to decide whether a line visualization or a mesh visualization has to be done. The first one is a map from one dimension into \(\mathbb {R}^3\) and the latter one a map from two dimensions to \(\mathbb {R}^3\). Here, the keys mesh/rows and mesh/cols are used to define mesh sizes (matrix sizes). Usually, you don’t have to care about that because the coordinate input routines already allow either one- or two-dimensional structure.

The precise rules how pgfplots distinguishes between line visualization and mesh visualization is as follows:

• 1. If the key mesh input=patches has been used, pgfplots relies on the current patch type (which has an inherent dimension).

• 2. For all other values of mesh input (like mesh input=lattice and mesh input=image), pgfplots proceeds as follows:

  • • It auto-completes the values for mesh/rows and mesh/cols (or uses their prescribed values).

  • • If these keys describe a matrix of size \(1\times N\) or \(N \times 1\), pgfplots assumes that it is a line.

  The “auto-completion” depends on how you provide your data.

  • • If you use \addplot3 expression, mesh/rows and mesh/cols are computed from the values samples and samples y. By default, \addplot3 expression always samples a mesh. If you want it to sample a line, set samples y=1 (or, equivalently, y domain=0:0).

  • • If you use \addplot3 table, \addplot3 coordinates, or \addplot3 file, you have basically two options: either you provide at least one of mesh/rows or mesh/cols explicitly, or you format the input table by means of end-of-scanline markers as outlined in empty line=auto or empty line=scanline. In this case, pgfplots counts scanline lengths and uses mesh/ordering to conclude how to determine the matrix values.

    Thus, if you have empty lines in your input table, pgfplots will automatically identify the matrix size.

    If you do not have empty lines, pgfplots expects at least one of mesh/rows or mesh/cols.

\addplot3 coordinates {coordinate list}; ¶

\addplot3[options] coordinates {coordinate list} trailing path commands; ¶

The \addplot3 coordinates method works like its two-dimensional variant, \addplot coordinates which is described in all detail at 31:

A long list of coordinates (x,y,z) is expected, separated by white spaces. The input list can be either an unordered series of coordinates, for example for scatter or line plots. It can also have matrix structure, in which case an empty line (which is equivalent to “\par”) marks the end of one matrix row. Matrix structure can also be provided if one of mesh/rows or mesh/cols is provided explicitly.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} % this yields a 3x4 matrix: \addplot3 [surf] coordinates { (0,0,0) (1,0,0) (2,0,0) (3,0,0) (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) }; \end{axis} \end{tikzpicture}

Here, \addplot3 reads a matrix with three rows and four columns. The empty lines separate one row from the following.

As for the two-dimensional \addplot coordinates, it is possible to provide (constant) mathematical expressions inside of single coordinates. The syntax (x,y,z) [meta] can be used just as for two dimensional \addplot coordinates to provide explicit color data; error bars are also supported.

\addplot3 table [column selection]{file}; ¶

\addplot3[options] table [column selection]{file} trailing path commands; ¶

The \addplot3 table input works in the same way as its two dimensional counterpart \addplot table. It only expects a column for the \(z\)-coordinates.

As for \addplot3 coordinates, an empty line in the file marks the end of one matrix row.

For matrix data in files, it is important to specify the ordering in which the matrix entries have been written. The default configuration is mesh/ordering=x varies, so you need to change it to mesh/ordering=y varies in case you have column by column ordering.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} % this yields a 3x4 matrix: \addplot3 [surf] table { 0 0 0 1 0 0 2 0 0 3 0 0 0 1 0 1 1 0.6 2 1 0.7 3 1 0.5 0 2 0 1 2 0.7 2 2 0.8 3 2 0.5 }; \end{axis} \end{tikzpicture}

\addplot3 file {name}; ¶

\addplot3[options] file {name} trailing path commands; ¶

Deprecation note:

If you have data files, you should generally use \addplot table. The input type \addplot file is almost the same, but considerably less powerful. It is only kept for backwards compatibility.

The \addplot3 file input method is the same as \addplot file – it only expects one more coordinate. Thus, the input file contains \(x_i\) in the first column, \(y_i\) in the second column and \(z_i\) in the third.

A further column is read after \(z_i\) if point meta=explicit has been requested, see the documentation of \addplot file at 147 for details.

As for \addplot3 coordinates, an empty line in the file marks the end of one matrix row.

For matrix data in files, it is important to specify the ordering in which the matrix entries have been written. The default configuration is mesh/ordering=x varies, so you need to change it to mesh/ordering=y varies in case you have column by column ordering.

/pgfplots/mesh/rows={integer} ¶

/pgfplots/mesh/cols={integer} ¶

For visualization of mesh or surface plots which need some sort of matrix input, the dimensions of the input matrix need to be known in order to visualize the plots correctly. The matrix structure may be known from end-of-row marks (empty lines as general end-of-scanline markers in the input stream) as has been described above.

If the matrix structure is not yet known, it is necessary to provide at least one of mesh/rows or mesh/cols where mesh/rows indicates the number of samples for \(y\)-coordinates whereas mesh/cols is the number of samples used for \(x\)-coordinates (see also mesh/ordering).

Thus, the following example is also a valid method to define an input matrix.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} % this yields also a 3x4 matrix: \addplot3 [surf,mesh/rows=3] coordinates { (0,0,0) (1,0,0) (2,0,0) (3,0,0) (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) }; \end{axis} \end{tikzpicture}

It is enough to supply one of mesh/rows or mesh/cols – the missing value will be determined automatically.

If you provide one of mesh/rows or mesh/cols, any end-of-row marker seen inside of input files or coordinate streams will be ignored.

/pgfplots/mesh/scanline verbose=true|false (initially false) ¶

Provides debug messages in the LaTeX output about end-of-scanline markers.

The message will tell whether end-of-scanlines have been found and if they are the same.

/pgfplots/mesh/ordering=x varies|y varies|rowwise|colwise (initially x varies) ¶

Allows to configure the sequence in which matrices (meshes) are read from \addplot3 coordinates, \addplot3 file or \addplot3 table.

Here, x varies means a sequence of points where \(n\)=mesh/cols successive points have the \(y\)-coordinate fixed. This is intuitive when you write down a function because \(x\) is horizontal and \(y\) vertical. Note that in matrix terminology, \(x\) refers to column indices whereas \(y\) refers to row indices. Thus, x varies is equivalent to rowwise ordering in this sense. This is the initial configuration.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[mesh/ordering=x varies] % this yields a 3x4 matrix in `x varies' % ordering: \addplot3 [surf] coordinates { (0,0,0) (1,0,0) (2,0,0) (3,0,0) (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) }; \end{axis} \end{tikzpicture}

Note that mesh/ordering is mandatory, even though the size of the matrix can be provided in different ways. The example above uses empty lines to mark scanlines. One could also say mesh/rows=3 and omit the empty lines.

Consequently, mesh/ordering=y varies provides points such that successive \(m\)=mesh/rows points form a column, i.e. the \(x\)-coordinate is fixed and the \(y\)-coordinate changes. In this sense, y varies is equivalent to colwise ordering, it is actually a matrix transposition.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[mesh/ordering=y varies] % this yields a 3x4 matrix in column-wise ordering: \addplot3 [surf] coordinates { (0,0,0) (0,1,0) (0,2,0) (1,0,0) (1,1,0.6) (1,2,0.7) (2,0,0) (2,1,0.7) (2,2,0.8) (3,0,0) (3,1,0.5) (3,2,0.5) }; \end{axis} \end{tikzpicture}

Again, note the subtle difference to the common matrix indexing where a column has the second index fixed. pgfplots refers to the way one would write down a function on a sheet of paper (this is consistent with how Matlab® displays discrete functions with matrices).

\addplot3 {math expression} ; ¶

\addplot3[options] {math expression} trailing path commands; ¶

Expression plotting also works in the same way as for two dimensional plots. Now, however, a two dimensional mesh is sampled instead of a single line, which may depend on x and y.

The method \addplot3 {math expr} visualizes the function \(f(x,y) = \)math expr where \(f \colon [x_1,x_2] \times [y_1,y_2] \to \mathbb {R}\). The interval \([x_1,x_2]\) is determined using the domain key, for example using domain=0:1. The interval \([y_1,y_2]\) is determined using the y domain key. If y domain is empty, \([y_1,y_2] = [x_1,x_2]\) will be assumed. If y domain=0:0 (or any other interval of length zero), it is assumed that the plot does not depend on y (thus, it is a line plot).

The number of samples in \(x\) direction is set using the samples key. The number of samples in \(y\) direction is set using the samples y key. If samples y is not set, the same value as for \(x\) is used. If samples y\(\,\le 1\), it is assumed that the plot does not depend on y (meaning it is a line plot).



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} % requires \usepgfplotslibrary{colorbrewer} \begin{tikzpicture} \begin{axis}[ colormap/PuBu, ] \addplot3 [surf] {y}; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[colorbar] \addplot3 [ surf, faceted color=blue, samples=15, domain=0:1,y domain=-1:1 ] {x^2 - y^2}; \end{axis} \end{tikzpicture}

Expression plotting sets mesh/rows and mesh/cols automatically; these settings don’t have any effect for expression plotting.

\addplot3 expression {math expression}; ¶

\addplot3[options] expression {math expression} trailing path commands; ¶

The syntax

\addplot3 {math expression};

as short-hand equivalent for

\addplot3 expression {math expression};

\addplot3 (x expression,y expression,z expression) ; ¶

\addplot3[options] (x expression,y expression,z expression) trailing path commands; ¶

A variant of \addplot3 expression which allows to provide different coordinate expressions for the \(x\)-, \(y\)- and \(z\)-coordinates. This can be used to generate parameterized plots.

Please note that \addplot3 (x,y,x^2) is equivalent to \addplot3 expression {x^2}.

Note further that since the complete point expression is surrounded by round braces, round braces inside of \(x\) expression, \(y\) expression or \(z\) expression need to be treated specially. Surround the expressions (which contain round braces) with curly braces:

\addplot3 ({\(x\) expr}, {\(y\) expr}, {\(z\) expr});

/pgfplots/mesh(no value)

\addplot+[mesh]

A mesh plot uses different colors for each mesh segment. The color is determined using a “color coordinate” which is also called “meta data” throughout this document. It is the same data which is used for surface and scatter plots as well, see Section 4.8.2. In the initial configuration, the “color coordinate” is the \(z\)-axis (or the \(y\)-axis for two dimensional plots). This color coordinate is mapped linearly into the current color map to determine the color for each mesh segment. Thus, if the smallest occurring color data is, say, \(-1\) and the largest is \(42\), points with color data \(-1\) will get the color at the lower end of the color map and points with color data \(42\) the color of the upper end of the color map.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [mesh] {x^2}; \end{axis} \end{tikzpicture}

A mesh plot can be combined with markers or with the scatter key which also draws markers in different colors.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} % requires \usepgfplotslibrary{colorbrewer} \begin{tikzpicture} \begin{axis}[ colormap/PuOr, ] \addplot3+ [ mesh, scatter, samples=10, domain=0:1, ] {x*(1-x)*y*(1-y)}; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ grid=major, view={210}{30}, ] \addplot3+ [ mesh, scatter, samples=10, domain=0:1, ] {5*x*sin(2*deg(x)) * y*(1-y)}; \end{axis} \end{tikzpicture}

Occasionally, one may want to hide the background mesh segments. This can be achieved using the surf plot handler (see below) and a specific fill color:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[title=With background] \addplot3 [mesh,domain=-2:2] {exp(-x^2-y^2)}; \end{axis} \end{tikzpicture} \begin{tikzpicture} \begin{axis}[title=Without background] \addplot3 [surf,fill=white,domain=-2:2] {exp(-x^2-y^2)}; \end{axis} \end{tikzpicture}

The fill color needs to be provided explicitly.

Details:

• • A mesh plot uses the same implementation as shader=flat to get one color for each single segment. Thus, if shader=flat mean, the color for a segment is determined using the mean of the color data of adjacent vertices. If shader=flat corner, the color of a segment is the color of the first adjacent vertex.²²

• • As soon as mesh is activated, color=mapped color is installed. This is necessary unless one needs a different color – but mapped color is the only color which reflects the color data.

  It is possible to use a different color using the color=color name as for any other plot.

• • It is easily possible to add mark=marker name to mesh plots, scatter is also possible. Scatter plots will use the same color data as for the mesh.

Mesh plots use the mesh legend style to typeset legend images.

/pgfplots/mesh/check=false|warning|error (initially error) ¶

Allows to configure whether an error is generated if mesh/rows \(\times \) mesh/cols does not equal the total number of coordinates.

If you know exactly what you are doing, it may be useful to disable the check. If you are unsure, it is best to leave the initial setting.

/pgfplots/z buffer=default|none|auto|sort|reverse x seq|reverse y seq|reverse xy seq (initially default) ¶

This key allows to choose between different \(z\) buffering strategies. A \(z\) buffer determines which parts of an image should be drawn in front of other parts. Since both, the graphics packages pgf and the final document format .pdf are inherently two dimensional, this work has to be done in TeX. Currently, several (fast) heuristics can be used which work reasonably well for simple mesh and surface plots. Furthermore, there is a (time consuming) sorting method which also works if the fast heuristics fails.

The \(z\) buffering algorithms of pgfplots apply only to a single \addplot command. Different \addplot commands will be drawn on top of each other, in the order of appearance.

The choice default checks if we are currently working with a mesh or surface plot and uses auto in this case. If not, it sets z buffer=none.

The choice none disables \(z\) buffering. This is also the case for two dimensional axes which don’t need \(z\) buffering.

The choice auto is the initial value for any mesh or surface plot: it uses a very fast heuristics to decide how to execute \(z\) buffering for mesh and surface plots. The idea is to reverse either the sequence of all \(x\)-coordinates, or those of all \(y\)-coordinates, or both. For regular meshes, this suffices to provide \(z\) buffering. In other words: the choice auto will use one of the three reverse strategies reverse * seq (or none at all). The choice auto, applied to patch plots, uses z buffer=sort since patch plots have no matrix structure.

The choice sort can be used for scatter, line, mesh, surface and patch plots. It sorts according to the depth of each point (or mesh segment). Sorting in TeX uses a slow algorithm and may require a lot of memory (although it has the expected runtime asymptotics \(\mathcal O(N \log N)\)). The depth of a mesh segment is just one number, currently determined as mean over the vertex depths. Since z buffer=sort is actually just a more intelligent way of drawing mesh segments on top of each other, it may still fail. Failure can occur if mesh segments are large and overlap at different parts of the segment (see Wikipedia “Painter’s algorithm”). If you experience problems of this sort, consider reducing the mesh width (the mesh element size) such that they can be sorted independently (for example automatically using patch refines=2, see the patchplots library).

The remaining choices apply only to mesh/surface plots (i.e. for matrix data) and do nothing more then their name indicates: they reverse the coordinate sequences of the input matrix (using quasi linear runtime). They should only be used in conjunction by z buffer=auto.

/pgfplots/surf(no value) ¶

\addplot+[surf]

A surface plot visualizes a two dimensional, single patch using different fill colors for each patch segment. Each patch segment is a (pseudo) rectangle, that means input data is given in form of a data matrix as is discussed in the introductory Section 4.6.2 about three dimensional coordinates.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [ surf, shader=interp, ] {x*y}; \end{axis} \end{tikzpicture}

The simplest way to generate surface plots is to use the plot expression feature, but – as discussed in Section 4.6.2 – other input methods like \addplot3 table or \addplot3 coordinates are also possible.

The appearance can be configured using colormaps, the value of the shader, faceted color keys and the current color and/or draw/fill color. As for mesh plots, the special color=mapped color is installed for the faces. The stroking color for faceted plots can be set with faceted color (see below for details).



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ grid=major, colormap/viridis, ] \addplot3 [ surf, samples=30, domain=0:1, ] {5*x*sin(2*deg(x)) * y}; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [ surf, faceted color=blue, ] {x+y}; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[colormap/cool] \addplot3 [surf,samples=10,domain=0:1,shader=interp] {x*(1-x)*y*(1-y)}; \end{axis} \end{tikzpicture} \begin{tikzpicture} \begin{axis}[colormap/cool] \addplot3 [surf,samples=25,domain=0:1,shader=flat] {x*(1-x)*y*(1-y)}; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[grid=major] \addplot3 [ surf, shader=interp, samples=25, domain=0:2, y domain=0:1, ] {exp(-x) * sin(pi*deg(y))}; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[grid=major] \addplot3 [ surf, shader=faceted, samples=25, domain=0:2, y domain=0:1, ] {exp(-x) * sin(pi*deg(y))}; \end{axis} \end{tikzpicture}

Details about the shading algorithm are provided below in the documentation of shader.

Surface plots use the mesh legend style to create legend images.

/pgfplots/shader=flat|interp|faceted|flat corner|flat mean|faceted interp (initially faceted) ¶

Configures the shader used for surface plots. The shader determines how the color data available at each single vertex is used to fill the surface patch.

The simplest choice is to use one fill color for each segment, the choice flat.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [ surf, shader=flat, samples=10, domain=0:1, ] {x^2*y}; \end{axis} \end{tikzpicture}

There are (currently) two possibilities to determine the single color for every segment:

• flat corner Uses the color data of one vertex to color the segment. The color of the first vertex determines the color of the entire segment. Note that pgfplots ensures that the outcome is always the same, even if the vertices are reordered due to z buffering or mesh/ordering.

  Note that pgfplots versions up to and including 1.12 chose one of them without respectiving reordering. In order to have the ordering independent of other features, you have to write compat=1.13 or newer.

• flat mean Uses the mean of all four color data values as segment color. This is the initial value as it provides symmetric colors for symmetric functions.

The choice flat is actually the same as flat mean. Please note that shader=flat mean and shader=flat corner also influence mesh plots – the choices determine the mesh segment color.

Another choice is shader=interp which uses Goraud shading (smooth linear interpolation of two triangles approximating rectangles) to fill the segments.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [ surf, shader=interp, samples=10, domain=0:1, ] {x^2*y}; \end{axis} \end{tikzpicture}

The shader=interp employs a low-level shading implementation which is currently available for the following drivers:

• • the postscript driver \def\pgfsysdriver{pgfsys-dvips.def},

• • the pdflatex driver \def\pgfsysdriver{pgfsys-pdftex.def},

• • the lualatex driver \def\pgfsysdriver{pgfsys-pdftex.def} and
  \def\pgfsysdriver{pgfsys-luatex.def},

• • the dvipdfmx driver \def\pgfsysdriver{pgfsys-dvipdfmx.def}.

For other drivers, the choice shader=interp will result in a warning and is equivalent to shader=flat mean. See also below for detail remarks.

Note that shader=interp,patch type=bilinear allows real bilinear interpolation, see the patchplots library.

The choice shader=faceted uses a constant fill color for every mesh segment (as for flat) and the value of the key /pgfplots/faceted color to draw the connecting mesh elements:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [ surf, shader=faceted, samples=10, domain=0:1, ] {x^2*y}; \end{axis} \end{tikzpicture}

The last choice is shader=faceted interp. As the name suggests, it is a mixture of interp and faceted in the sense that each element is shaded using linear triangle interpolation (see also the patchplots library for bilinear interpolation) in the same way as for interp, but additionally, the edges are colored in faceted color:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [ surf, shader=faceted interp, samples=10, domain=0:1, ] {x^2*y}; \end{axis} \end{tikzpicture}

In principle, there is nothing wrong with the idea as such, and it looks quite good – but it enlarges the resulting PDF document considerably and might take a long time to render. It works as follows: for every mesh element (either triangle for patch plots or rectangle for lattice plots), it creates a low level shading. It then fills the single mesh element with that shading, and strokes the edges with faceted color. The declaration of that many low level shadings is rather inefficient in terms of PDF objects (large output files) and might render slowly.²³ For orthogonal plots (like view={0}{90}), the effect of faceted interp can be gained with less cost if one uses two separate \addplot commands: one with surf and one with mesh. Handle this choice with care.

Details:

• • All shaders support z buffer=sort (starting with version 1.4).

• • The choice shader=faceted is the same as shader=flat – except that it uses a special draw color.

  So, shader=faceted has the same effect as

  shader=flat,draw=\pgfkeysvalueof{/pgfplots/faceted color}.

• • The flat shader uses the current draw and fill colors. They are set with color=mapped color and can be overruled with draw=draw color and fill=fill color. The mapped color always contains the color of the color map.

• • You easily add mark=plot mark to mesh and/or surface plots or even colored plot marks with scatter. The scatter plot feature will use the same color data as for the surface.

  But: Markers and surfaces do not share the same depth information. They are drawn on top of each other.

• • Remarks on shader=interp:

  • – It uses the current color map in any case, ignoring draw and fill.

  • – For surface plots with lots of points, shader=interp produces smaller pdf documents, requires less compilation time in TeX and requires less time to display in Acrobat Reader than shader=flat.

  • – The postscript driver truncates coordinates to 24 bit – which might result in a loss of precision (the truncation is not very intelligent). See the surf shading/precision key for details. To improve compatibility, this 24 bit truncation algorithm is enabled by default also for PDF documents.

  • – The choice shader=interp works well with either Acrobat Reader or recent versions of free viewers.²⁴ However, some free viewers show colors incorrectly (like evince). I hope this message will soon become outdated… if not, provide bug reports to the Linux community to communicate the need to improve support for Type 4 (patch) and Type 5 PDF (surf) and Type 7 (patch and elements of the patchplots library) shadings.

  • – The interp shader yields the same outcome as faceted interp,faceted color=none, although faceted interp requires much more resources.

Note that the shader always interacts with colormap access. In particular, colormap access=piecewise constant combined with shader=interp results in a filled contour plot, see Section 4.6.9 for details.

/pgfplots/faceted color={color name} (initially mapped color!80!black) ¶

Defines the color to be used for meshes of faceted surface plots.

Set faceted color=none to disable edge colors.

/pgfplots/mesh/interior colormap={map name}{colormap specification} ¶

/pgfplots/mesh/interior colormap name={map name} ¶

Allows to use a different colormap for the “other side” of the surface.

Each mesh has two sides: one which “points” to the view’s origin and one which points away from it. This key allows to define a second colormap for the side which points away from the view’s origin. The motivation is to distinguish between the outer side and the interior parts of a surface:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ axis lines=center, axis on top, xlabel={$x$}, ylabel={$y$}, zlabel={$z$}, domain=0:1, y domain=0:2*pi, xmin=-1.5, xmax=1.5, ymin=-1.5, ymax=1.5, zmin=0.0, mesh/interior colormap= {blueblack}{color=(black) color=(blue)}, colormap/blackwhite, samples=10, samples y=40, z buffer=sort, ] \addplot3 [surf] ({x*cos(deg(y))},{x*sin(deg(y))},{x}); \end{axis} \end{tikzpicture}

The interior colormap is often the one for the “inner side”. However, the orientation of the surface depends on its normal vectors: pgfplots computes them using the right-hand-rule. The right-hand-rule applied to a triangle means to take the first encountered point, point the thumb in direction of the second point and the first finger in direction of the third point. Then, the normal for that triangle is the third finger (i.e. the cross product of the involved oriented edges). For rectangular patches, pgfplots uses the normal of one of its triangles.²⁵ Consequently, mesh/interior colormap will only work if the involved patch segments are consistently oriented.

A patch whose normal vector points into the same direction as the view direction uses the standard colormap name. A patch whose normal vector points into the opposite direction (i.e. in direction of the viewport) uses mesh/interior colormap.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ hide axis, xlabel=$x$,ylabel=$y$, mesh/interior colormap name=hot, colormap/blackwhite, ] \addplot3 [domain=-1.5:1.5,surf] {-exp(-x^2-y^2)}; \end{axis} \end{tikzpicture}

The implementation of mesh/interior colormap works well for most examples; in particular, if the number of samples is large enough to resolve the boundary between inner and outer colormap. However, it might still produce spurious artifacts:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title=Example needing fine-tuning, xlabel=$x$, ylabel=$y$, ] \addplot3 [surf, mesh/interior colormap={blueblack}{ color=(black) color=(blue) }, colormap/blackwhite, domain=0:1, ] { sin(deg(8*pi*x))* exp(-20*(y-0.5)^2) + exp(-(x-0.5)^2*30 - (y-0.25)^2 - (x-0.5)*(y-0.25)) }; \end{axis} \end{tikzpicture}

The previous example has need for improvement with respect to a couple of aspects: first, it has small overshoots near some of the meshes vertices (especially on top of the hills). These can be fixed using miter limit=1. Second, the boundary between blue and black is incorrect. This can be improved by means of an increased sampling density (samples=31). In addition, we can configure pgfplots to move the boundary between the two colormaps in favor of the blue region using mesh/interior colormap thresh as follows:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title=Example of before with fine-tuning, xlabel=$x$, ylabel=$y$, ] \addplot3 [ surf, mesh/interior colormap={blueblack}{ color=(black) color=(blue) }, % slightly increase sampling quality (was 25): samples=31, % avoids overshooting corners: miter limit=1, % move boundary between inner and outer: mesh/interior colormap thresh=0.1, colormap/blackwhite, domain=0:1, ] { sin(deg(8*pi*x))* exp(-20*(y-0.5)^2) + exp(-(x-0.5)^2*30 - (y-0.25)^2 - (x-0.5)*(y-0.25)) }; \end{axis} \end{tikzpicture}

This improves the display.

Call for volunteers:

it would be nice if the fine-tuning of these keys would be unnecessary. If someone has well-founded suggestions (like knowledge and perhaps exhaustive experiments) on how to improve the feature, let me know.

Note that mesh/interior colormap cannot be combined with mesh/refines currently.

Note that mesh/interior colormap will increase compilation times due to the computation of normal vectors.

/pgfplots/mesh/interior colormap thresh={Number between \(-1.0\) and \(+1.0\)} (initially 0) ¶

A threshold which moves the boundary between the colormap and interior colormap in favor of colormap (if the value is negative) or in favor of interior colormap (if the value is positive).

The extreme value \(-1\) essentially deactivates interior colormap whereas the other extreme \(+1\) deactivates colormap.

See above for an example.

/pgfplots/surf shading/precision=pdf|postscript|ps (initially postscript) ¶

A key to configure how the low level driver for shader=interp writes its data. The choice pdf uses 32 bit binary coordinates (which is lossless). The resulting .pdf files appear to be correct, but they can’t be converted to postscript – the converter software always complains about an error.

The choice postscript (or, in short, ps) uses 24 bit truncated binary coordinates. This results in both, readable .ps and .pdf files. However, the truncation is lossy.

If anyone has ideas how to fix this problem: let me know. As far as I know, Postscript should accept 32 bit coordinates, so it might be a mistake in the shading driver.

/pgfplots/mesh/color input=colormap|explicit|explicit mathparse (initially colormap) ¶

Allows to configure how pgfplots expects color input for surface plots.

The choice colormap uses the standard colormaps. This particular choice expects scalar values of point meta which are mapped linearly into the colormap. It resembles the surface plots which are explained in more detail in Section 4.6.6. It is the default configuration and covers (probably) most common use cases.

The choice explicit expects explicitly provided point meta of symbolic form: every coordinate of your input coordinate stream is supposed to have an explicitly defined color as point meta. Here, “explicitly provided” refers to point meta=explicit symbolic. This choice and the available color formats are explained in all detail in the following subsections.

The choice explicit mathparse is similar to explicit, but it allows to provide just one math expression which is evaluated for every coordinate. The math expression can be of the form rgb=x,y,0.5 in which case x is used to define the “red” component, y is used to define the “green” component and the “blue” component is fixed to 0.5. This key is also explained in more detail in the following subsections.

/pgfplots/mesh/colorspace explicit color input=rgb|rgb255|cmy|cmyk|cmyk255|gray|wave|hsb
|Hsb|HTML (initially rgb) ¶

If the input color has no color model, the color components are interpreted as color in the color model specified as argument to this key.

This key has just one purpose: to omit the color model if it is the same for lots of points anyway.

/pgfplots/mesh/colorspace explicit color output=rgb|cmyk|gray (initially rgb) ¶

Any color which is encountered by the survey phase (i.e. while inspecting the point meta value) is immediately transformed into the color space configured as mesh/colorspace explicit color output.

Note that this option has no effect if you told xcolor to override the color space globally. More precisely, the use of

copy \usepackage[cmyk]{xcolor}

or, alternatively,

copy \selectcolormodel{cmyk}

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.

The transformed color is used for any color interpolation. In most cases, this is done by the shader, but it applies to patch refines and patch to triangles as well.

Because the transformed color is used for color interpolation, the list of available output color spaces is considerably smaller than the available input color spaces. Only the device color spaces rgb, gray, and cmyk are available as value for mesh/colorspace explicit color output.

Any necessary colorspace transformations rely on the xcolor package.²⁶ Note that colorspace transformations are subject to nearest color matching, i.e. they are less accurate. This is typically far beyond pure rounding issues; it is caused by the fact that these color spaces are actually so different that transformations are hard to accomplish. If you can specify colors immediately in the correct color space, you can eliminate such transformations.

Here is the same shading, once with CMYK output and once with RGB output. Depending on your output media (screen or paper), you will observe slightly different colors when comparing the pictures.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[title=RGB shading] \addplot [ patch, shader=interp, mesh/color input=explicit, mesh/colorspace explicit color output=rgb, data cs=polar, ] coordinates { (90,4) [color=red] (210,4) [color=green] (-30,4) [color=blue] }; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[title=CMYK shading] \addplot [ patch, shader=interp, mesh/color input=explicit, mesh/colorspace explicit color output=cmyk, data cs=polar, ] coordinates { (90,4) [color=red] (210,4) [color=green] (-30,4) [color=blue] }; \end{axis} \end{tikzpicture}

This key is similar to the related key colormap default colorspace, although the values can be chosen independently.

/pgfplots/contour lua={options with ‘contour/’ or ‘contour external/’ prefix} ¶

\addplot+[ contour lua={options with ‘contour/’ or ‘contour external/’ prefix}]

This algorithm was implemented and contributed by Francesco Poli

This is a high level contour plot interface. It expects matrix data in the same way as two dimensional surf or mesh plots do. It then computes contours and visualizes them.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={0}{90}] \addplot3 [ contour lua ] {x*y}; \end{axis} \end{tikzpicture}

The example uses \addplot3 together with expression plotting, that means the input data is of the form \((x_i,y_i,f(x_i,y_i))\). The view={0}{90} flag means “view from top”, otherwise the contour lines would have been drawn as \(z\) value:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [ contour lua ] {exp(0-x^2-y^2)}; \end{axis} \end{tikzpicture}

As mentioned, you can use any of the pgfplots input methods as long as it yields matrix output. Thus, we can reuse our introductory example of matrix data, this time with inline data:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={0}{90}] \addplot3 [ contour lua ] coordinates { (0,0,0) (1,0,0) (2,0,0) (3,0,0) (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) }; \end{axis} \end{tikzpicture}

What happens behind the scenes is that pgfplots takes the input matrix and writes all encountered coordinates to a temporary file, including the end-of-scanline markers. Then, it generates a small lua script and invokes a lua algorithm to compute the contour coordinates, writing everything into a temporary output file. Afterwards, it includes lua’s output file just as if you’d write \addplot3[contour prepared] file {temporaryfile};.

All this invocation of lua, including input/output file management is transparent to the user. It only requires two things: first of all, it requires matrix data as input.²⁹

The contouring algorithm of contour lua accepts \((x,y,z)\) and, in addition the point meta. Its contour information is always based on point meta. Usually, point meta and \(z\) are the same. But it is also possible to use a different point meta:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ xlabel={$x$}, ylabel={$y$}, zlabel={$z$}, view/h=70, view/v=50, ] % z= -x+y \addplot3[surf,samples=2,shader=interp] table { x y z -5 -5 0 5 -5 -10 -5 5 10 5 5 0 }; % same data, but with contour % and color data v= x+y : \addplot3[ contour lua={number=3}, point meta=\thisrow{v}, ] table { x y z v -5 -5 0 -10 5 -5 -10 0 -5 5 10 0 5 5 0 10 }; \end{axis} \end{tikzpicture}

The resulting data can be projected onto a separate slice, for example using z filter.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot3 [ surf, shader=interp ] coordinates { (0,0,0) (1,0,0) (2,0,0) (3,0,0) (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) }; \addplot3 [ contour lua, z filter/.code={\def\pgfmathresult{1}}, ] coordinates { (0,0,0) (1,0,0) (2,0,0) (3,0,0) (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) }; \end{axis} \end{tikzpicture}

There are several fine-tuning parameters of the input/output file management, and it is even possible to invoke different programs than lua (see contour gnuplot). These details are discussed at the end of this section.

/pgfplots/contour/number={integer} (initially 5) ¶

Configures the number of contour lines which should be produced by any contouring algorithm. The value is applied to both contour lua and contour filled.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title={$x \exp(-x^2-y^2)$}, domain=-2:2,enlarge x limits, view={0}{90}, ] \addplot3 [ contour lua={number=14, labels=false}, thick, ] {exp(-x^2-y^2)*x}; \end{axis} \end{tikzpicture}

It is also possible to change the /pgf/number format settings, see the documentation for the contour/every contour label style below.

Note that contour/number has no effect on contour prepared.

/pgfplots/contour/levels={list of levels} (initially empty) ¶

Configures the number of contour lines which should be produced by any contouring algorithm by means of a list of discrete levels.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title={$x \exp(-x^2-y^2)$}, domain=-2:2, enlargelimits, view={0}{90}, ] \addplot3 [ contour lua={levels={-0.1,-0.2,-0.6}}, thick, ] {exp(-x^2-y^2)*x}; \end{axis} \end{tikzpicture}

It is also possible to change the /pgf/number format settings, see the documentation for the contour/every contour label style below.

This key has higher precedence than contour/number, i.e. if both are given, contour/levels will be active.

Note that contour/levels has no effect on contour prepared.

/pgfplots/contour/contour dir=x|y|z (initially z) ¶

Note: The key contour dir was introduced in order to support external contouring algorithms which operate on three coordinates (like contour gnuplot). However, contour lua operates on \((x,y,z)\) and point meta and can achieve the same effect using point meta=x! Thus, this key has become of less importance since contour lua.

This key allows to generate contours with respect to another direction.

The input data is the same as before – it has to be given in matrix form. The key contour dir configures the algorithm to compute contours along the provided direction.

This function is also available for parameterized surfaces.

Note, however, that each contour line receives a single color. This is what one expects for a contour plot: it has a single style, and a single contour level. Note furthermore that the color which is assigned to a contour plot with contour dir=x is different compared with the color assigned to a contour plot with contour dir=z: the argument of contour dir implicitly defines the argument for point meta (also known as color data). More precisely, a contour plot with contour dir=x has point meta=x whereas a contour plot with contour dir=z uses point meta=z.

If you would like to have individually colored segments inside of contours, you have to use a different plot handler. There is a simple alternative which works well in many cases: you can use a standard mesh plot combined with patch type=line:

Here, we did not generate a contour plot. We generated a mesh plot with patch type=line. The choice patch type=line causes an inherently one-dimensional plot as opposed to the default matrix style visualization which would be generated by mesh in different cases. Since a mesh plot uses one color for every patch segment, we have a lot of freedom to color the segments. In the example above, we have the default configuration point meta=z, i.e. the \(z\) value defines the color.

The fact that a mesh plot with patch type=line yields almost the same output as contour dir=y is an artifact of the scanline encoding. Our example uses \addplot3 expression which relies on mesh/ordering=x varies. If we visualize the resulting matrix by means of patch type=line, the visualization follows the scanlines which vary along the \(x\)-axis. In our example, we used samples y=10 to control the number of “contour lines”.

A consequence of the previous paragraph is that we have a more challenging task at hand if we want to get the same effect as contour dir=x: we would need mesh/ordering=y varies. In our case, we would need to transpose the data matrix. For \addplot3 expression, this is relatively simple: we can exchange the meaning of x and y to get a transposition:

This is the same example as above – but as you noted, the meaning of x and y in the expression has been exchanged and the notation has been switched to a parametric plot. Such an approach is also possible for data files, but pgfplots cannot transpose the matrix ordering on its own.

Coming back to contour dir, we can also use its output to generate several contour projections using coordinate filters.

The preceding example uses a fixed draw color combined with x filter, y filter, and z filter to fix the contours in one of the axis planes.

Technical background:

This section is probably unnecessary and can be skipped. The key contour dir is implemented by means of coordinate permutations. Since contouring algorithms always support contour dir=z, it is relatively simple to compute \(z\)–contour lines from input matrixes \(X, Y, Z\). The choice contour dir=z key simply takes the input as is. The choice contour dir=x reorders the input coordinates to yzx. The choice contour dir=y reorders the input coordinates to xzy. All this reordering is applied before coordinates are handed over to the contouring algorithm (see contour external) and is undone when reading the results back from the contouring algorithm. That means that contour dir is also available for contour prepared. In this context, contour prepared is supposed to be the output of some contouring algorithm. Its input coordinates are automatically reordered according to the inverse permutation. This allows to draw \(x\) or \(y\) contours which are given in the prepared format.

/pgfplots/contour gnuplot={options with ‘contour/’ or ‘contour external/’ prefix} ¶

\addplot+[ contour gnuplot={options with ‘contour/’ or ‘contour external/’ prefix}]

This is a high level contour plot interface. It expects matrix data in the same way as two dimensional surf or mesh plots do. It then computes contours and visualizes them. The handler contour gnuplot works in the very same way as contour lua and produces results of comparable quality. All the keys and examples mentioned above apply for contour gnuplot as well. However, you necessarily need to apply the following steps before you can use contour gnuplot:

• 1. install gnuplot on your system.

• 2. Ensure that you can invoke gnuplot from a terminal (like cmd.exe or bash). To this end, you will need to add gnuplot to the PATH environment variable.

• 3. When invoking pdflatex, you need to enable system calls.

  For TeXLive, this is pdflatex -shell-escape. For MiKTeX, the system uses pdflatex -enable-write18 . Some TeX distributions require you to use two slashes for the option.

See also the documentation for plot gnuplot for a related section.

The usage is the same as for contour lua, so please refer to the contour lua and its examples.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={0}{90}] \addplot3 [ contour gnuplot ] {x*y}; \end{axis} \end{tikzpicture}



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={0}{90}] \addplot3 [ contour gnuplot={number=6} ] {exp(-x^2-y^2)}; \end{axis} \end{tikzpicture}

/pgfplots/contour prepared={options with ‘contour/’ prefix} ¶

\addplot+[contour prepared={options with ‘contour/’ prefix}]

A plot handler which expects already computed contours on input and visualizes them. It cannot compute contours on its own.

/pgfplots/contour prepared format=standard|matlab (initially standard) ¶

There are two accepted input formats. The first is a long sequence of coordinates of the form \((x,y,z)\) where all successive coordinates with the same \(z\) value make up a contour level (this is only part of complete truth, see below). The end-of-scanline markers (empty lines in the input) mark an interruption in one contour level.

For example, contour prepared format=standard could be³⁰



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot [contour prepared] table { 2 2 0.8 0.857143 2 0.6 1 1 0.6 2 0.857143 0.6 2.5 1 0.6 2.66667 2 0.6 0.571429 2 0.4 0.666667 1 0.4 1 0.666667 0.4 2 0.571429 0.4 3 0.8 0.4 0.285714 2 0.2 0.333333 1 0.2 1 0.333333 0.2 2 0.285714 0.2 3 0.4 0.2 }; \end{axis} \end{tikzpicture}

Note that the empty lines are not necessary in this case: empty lines make only a difference if they occur within the same contour level (i.e. if the same \(z\) value appears above and below of them).

The choice contour prepared format=matlab expects two-dimensional input data where the contour level and the number of elements of the contour line are provided as \(x\)- and \(y\)-coordinates, respectively, of a leading point. Such a format is used by matlab’s contour algorithms, i.e. it resembles the output of the Matlab commands data=contour(...) or data=contourc(...).



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis} \addplot [ contour prepared, contour prepared format=matlab, ] table { % (0.2,5) ==> contour `0.2' (x), 5 points follow (y): 2.0000000e-01 5.0000000e+00 3.0000000e+00 4.0000000e-01 2.0000000e+00 2.8571429e-01 1.0000000e+00 3.3333333e-01 3.3333333e-01 1.0000000e+00 2.8571429e-01 2.0000000e+00 % (0.4,5) ==> contour `0.4', consists of 5 points 4.0000000e-01 5.0000000e+00 3.0000000e+00 8.0000000e-01 2.0000000e+00 5.7142857e-01 1.0000000e+00 6.6666667e-01 6.6666667e-01 1.0000000e+00 5.7142857e-01 2.0000000e+00 % (0.6,6) ==> contour `0.6', has 6 points 6.0000000e-01 6.0000000e+00 2.6666667e+00 2.0000000e+00 2.5000000e+00 1.0000000e+00 2.0000000e+00 8.5714286e-01 1.0000000e+00 1.0000000e+00 1.0000000e+00 1.0000000e+00 8.5714286e-01 2.0000000e+00 }; \end{axis} \end{tikzpicture}

In case you use Matlab, you can generate such data with

[x,y]=meshgrid(linspace(0,1,15));
data=contour(x,y,x.*y);
data=data';
save 'exporteddata.dat' data -ASCII

As already mentioned in the beginning, the \(z\)-coordinate is not necessarily the coordinate used to delimit contour levels. In fact, the point meta data is acquired here, i.e. you are free to use whatever \(z\) coordinate you want as long as you have a correct point meta value. The example from above could be modified as follows:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title=Separating $z$ from Color Value, xlabel=$x$, ylabel=$y$, ] \addplot3 [ contour prepared, point meta=\thisrow{level}, ] table { x y z level 0.857143 2 0.4 0.6 1 1 0.6 0.6 2 0.857143 0.6 0.6 2.5 1 0.6 0.6 2.66667 2 0.4 0.6 0.571429 2 0.2 0.4 0.666667 1 0.4 0.4 1 0.666667 0.4 0.4 2 0.571429 0.4 0.4 3 0.8 0.2 0.4 0.285714 2 0 0.2 0.333333 1 0.2 0.2 1 0.333333 0.2 0.2 2 0.285714 0.2 0.2 3 0.4 0 0.2 }; \end{axis} \end{tikzpicture}

The example above uses different \(z\)-coordinates for each first and each last point on contour lines. The contour lines as such are defined by the level column since we wrote point meta=\thisrow{level}. Such a feature also allows contour prepared for nonstandard axes, compare the examples for the ternary lib at 1318.

/pgfplots/contour/draw color={color} (initially mapped color) ¶

Defines the draw color for every contour. Note that only mapped color actually depends on the contour level.

/pgfplots/contour/labels={true,false} (initially true) ¶

Configures whether contour labels shall be drawn or not.

/pgfplots/contour lua/corners=true|false (initially false) ¶

A detail option for contour lua which allows to modify how sharp corners in the input data are handled by the contouring algorithm. The choice corners=true adds more points to the contour lines (“corners”).

 

copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={0}{90},small] \addplot3 [ contour lua={corners,labels=false} ] {x*y}; \end{axis} \end{tikzpicture} ~ \begin{tikzpicture} \begin{axis}[view={0}{90},small] \addplot3 [ contour lua={labels=false} ] {x*y}; \end{axis} \end{tikzpicture}

/pgfplots/contour/label distance={dimension} (initially 70pt) ¶

Configures the distance between adjacent contour labels within the same contour level.

/pgfplots/contour/every contour plot(style, no value) ¶

A style which is installed as soon as either contour or contour external is set.

The initial value is

copy \pgfplotsset{ contour/every contour plot/.style={ /pgfplots/legend image post style={sharp plot}, }, }

/pgfplots/contour/every contour label(style, no value) ¶

Allows to customize contour labels. The preferred way to change this style is the contour label style={options} method, see below.

The initial value is

copy \pgfplotsset{ contour/every contour label/.style={ sloped, transform shape, inner sep=2pt, every node/.style={mapped color!50!black,fill=white}, /pgf/number format/relative={\pgfplotspointmetarangeexponent}, }, }

Note that \pgfplotspointmetarangeexponent\(=e\) where \(\pm m \cdot 10^e\) is the largest occurring label value (technically, it is the largest occurring value of point meta).

The following example modifies the /pgf/number format styles for contour labels:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ title={$x \exp(-x^2-y^2)$}, domain=-2:2,enlarge x limits, view={0}{90}, ] \addplot3 [ contour lua={ scanline marks=required, number=14, contour label style={ /pgf/number format/fixed, /pgf/number format/precision=1, }, }, thick, ] {exp(0-x^2-y^2)*x}; \end{axis} \end{tikzpicture}

/pgfplots/contour/contour label style={key-value-list} ¶

An abbreviation for contour/every contour label/.append style={key-value-list}.

It appends options to the already existing style contour/every contour label.

/pgfplots/contour/labels over line(style, no value) ¶

A style which changes every contour label such that labels are right over the lines, without fill color.



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={0}{90}] \addplot3 [ contour lua={ labels over line, number=9, }, ] {x*y}; \end{axis} \end{tikzpicture}

/pgfplots/contour/handler(style, no value) ¶

Allows to modify the plot handler which connects the points of a single contour level.

The initial value is

copy \pgfplotsset{contour/handler/.style={/tikz/sharp plot}}

but a useful alternative might be the smooth handler:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[view={0}{90}] \addplot3 [ contour lua={ levels={0.1,0.2,0.5,1,2,5}, labels=false, handler/.style=smooth, }, ] {2*sqrt(x^2+y^2+(-0.5*(x^2-y^2)))}; \end{axis} \end{tikzpicture}

Unfortunately, the TikZ handler smooth has its limitations for such plots, you may need to play around with the number of samples.

/pgfplots/contour/label node code/.code={...} ¶

A low-level interface to modify how contour labels are placed.

The initial value is

copy \pgfplotsset{ contour/label node code/.code={\node {\pgfmathprintnumber{#1}};}, }

/pgfplots/contour external={options with ‘contour/’ or ‘contour external/’ prefix} ¶

\addplot+[ contour external={options with ‘contour/’ or ‘contour external/’ prefix}]

This handler constitutes a generic interface to external programs to compute contour lines. The contour gnuplot method is actually a special case of contour external. At the time of this writing, even contour lua is a special case of contour external.

/pgfplots/contour external/file={base file name} (initially empty) ¶

The initial configuration is to automatically generate a unique file name.

/pgfplots/contour external/scanline marks=false|if in input|required|true (initially if in input) ¶

Controls how contour external writes end-of-scanline markers.

The choice false writes no such markers at all. In this case, script should contain mesh/rows and/or mesh/cols.

The choice if in input generates end-of-scanline markers if they appear in the provided input data (either as empty lines or if the user provided at least two of the three options mesh/rows, mesh/cols, or mesh/num points explicitly).

The choice required works like if in input, but it will fail unless there really was such a marker.

The choice true is an alias for required.

/pgfplots/contour external/script={code for external program} (initially empty) ¶

Provides template code to generate a script for the external program. Inside of code for external program, the placeholder \infile will expand to the temporary input file and \outfile to the temporary output file. The temporary \infile is a text file containing one point on each line, in the specified by script input format, separated by tabstops. Whenever a scanline is complete, an empty line is issued (but only if these scanline markers are found in the input stream as well). The complete set of scanlines forms a matrix. There are no additional comments or extra characters in the file. The macro \ordering will expand to 0 if the matrix is stored in mesh/ordering=x varies and \ordering will be 1 for mesh/ordering=y varies.

Inside of code for external program, you can also use \pgfkeysvalueof{/pgfplots/mesh/rows} and \pgfkeysvalueof{/pgfplots/mesh/cols}; they expand to the matrix’ size. Similarly, \pgfkeysvalueof{/pgfplots/mesh/num points} expands to the total number of points.

Inside of code for external program, the macro \thecontournumber is defined to be the value \pgfkeysvalueof{/pgfplots/contour/number} and \thecontourlevels contains the value \pgfkeysvalueof{/pgfplots/contour/levels}. These two macros simplify conditional code.

If you need one of the characters ["|;:#'`] and some macro package already uses the character for other purposes, you can prepend them with a backslash, i.e. write \" instead of ".

/pgfplots/contour external/script input format=x y meta meta|x y z meta (initially x y meta meta) ¶

Defines what kind of input file the external script expects. Usually, contouring algorithms expect three coordinates and the last one is the one to which the contour computation is applied. Such algorithms need x y meta meta and the last coordinate needs to be ignored.

However, there it is possible to define contour algorithms which expect four input coordinates (x,y,z,meta) where the fourth coordinate defines the contour level. In such a case, you have to use x y z meta as choice. A related key is output point meta in this context.

/pgfplots/contour external/script type=system call|lua (initially system call) ¶

Allows to define the type of script. The choice system call invokes an external program. The choice lua writes the script into a lua file and invokes the lua interpreter. This is only supported if you use lualatex instead of pdflatex. It is unrelated to lua backend.

/pgfplots/contour external/@before cmd(initially empty) ¶

/pgfplots/contour external/@after cmd(initially empty) ¶

These keys allow callbacks for integrators. Any TeX code inside of them is invoked before/after the script.

/pgfplots/contour external/script extension={extension} (initially script) ¶

The file name extension for the temporary script.

/pgfplots/contour external/cmd={system call} (initially empty) ¶

A template to generate system calls for the external program. Inside of system call, you may use \script as placeholder for the filename which contains the result of contour external/script and \scriptbase as placeholder for the same, but without file extension.

/pgfplots/contour external/output point meta={point meta read from result of external tool} (initially empty) ¶

Allows to customize the point meta configuration which is applied to the result of the external tool.

In contour external, the value of point meta is used to generate the input \(z\)-coordinate for the external tool.

As soon as the external tool computed contour lines, its output is read and interpreted as contour lines – and the value of output point meta determines the value of point meta which will be used to visualize the result.

An empty value means to use the \(z\)-coordinate returned by the external tool.

Any other value is interpreted as a valid choice of point meta.

/pgfplots/contour gnuplot(style, no value)

The initial configuration is

copy \pgfplotsset{ contour gnuplot/.style={ contour external={ script={ unset surface; \ifx\thecontourlevels\empty set cntrparam levels \thecontournumber; \else set cntrparam levels discrete \thecontourlevels; \fi set contour; set table \"\outfile\"; splot \"\infile\"; }, cmd={gnuplot \"\script\"}, #1,% }, }, }

Note that contour gnuplot requires explicit scanline markers in the input stream, and it assumes mesh/ordering=x varies.

Note that contour external lacks the intelligence to detect changes; it will always regenerate the output (unless the -shell-escape feature is not active).

/pgfplots/contour filled={options with ‘contour/’ prefix} ¶

\addplot+[ contour filled={options with ‘contour/’ prefix}]

Beware: Viewer Limitations

The following paragraph makes uses of 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.

This plot handler visualizes patches or surfaces by means of filled segments: points on the surface will be colored based on their point meta value. The point meta value is mapped into a sequence of intervals, and each interval has its own color. The intervals, in turn, are part of a colormap.

The number of contour levels is defined by means of contour/number, just as for contour external:

In addition to selecting a number of contour levels, you can select a predefined list of levels:

A filled contour plot merely affects the appearance of patch segments, so you can easily adopt axis options like view.

pgfplots implements the plot handler contour filled in almost the same way as surf: it expects the very same input format (i.e. coordinates in matrix form from any supported coordinate input stream) and expects numeric point meta. In order to determine the correct color, pgfplots evaluates point meta for each encountered vertex in the input matrix and interpolates any values of point meta on mesh segments. The interpolation scheme is normally linear, but you can write patch type=bilinear if you want bilinear interpolation of point meta (higher quality somewhat bigger output files; we come back to this at the end of this plot handler). Finally, each interpolated point meta is mapped into a colormap using colormap access=const.

The colormap in question is specific to contour filled: it is defined after the survey phase and is called internal:contourfilled. It is created using the of colormap functionality (see its reference for details). pgfplots uses target pos min and target pos max to ensure that the resulting colormap fits into the range point meta min\(:\)point meta max.