How to Make a PGFPlots Contour Plot from Matrix Data

A matrix of values can be plotted in PGFPlots as a sampled surface. Give each entry its grid coordinates $(x,y)$ and its value $z$, then tell PGFPlots how the points are arranged. Viewing the surface from directly above produces a color map; adding contour lines shows where the data has equal values.

The example below uses a $4\times4$ grid. It draws the color map and overlays contours at three specified levels.

Complete example

\documentclass{standalone}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}

\begin{document}
\begin{tikzpicture}
\begin{axis}[
    view={0}{90},
    xlabel={$x$},
    ylabel={$y$},
    colorbar,
    colormap/viridis,
    point meta min=0,
    point meta max=4,
]
\addplot3[
    surf,
    shader=interp,
    mesh/rows=4,
    point meta=z,
] table {
    x y z
    0 0 4
    1 0 2
    2 0 2
    3 0 4
    0 1 2
    1 1 0
    2 1 0
    3 1 2
    0 2 2
    1 2 0
    2 2 0
    3 2 2
    0 3 4
    1 3 2
    2 3 2
    3 3 4
};
\addplot3[
    contour gnuplot={levels={1,2,3},labels=false},
    mesh/rows=4,
    draw=black,
    thick,
] table {
    x y z
    0 0 4
    1 0 2
    2 0 2
    3 0 4
    0 1 2
    1 1 0
    2 1 0
    3 1 2
    0 2 2
    1 2 0
    2 2 0
    3 2 2
    0 3 4
    1 3 2
    2 3 2
    3 3 4
};
\end{axis}
\end{tikzpicture}
\end{document}

Save the file as, for example, contour.tex. The example uses PGFPlots’ contour gnuplot feature, so Gnuplot must be installed and available to the TeX system. Compile with shell escape enabled, such as pdflatex -shell-escape contour.tex. Some hosted LaTeX editors disable shell escape; in that case, use an editor or build setup that permits the required external call.

How the matrix is represented

The table has three columns: x, y, and z. The z column is the matrix value, while x and y identify the column and row of that value. The data are listed row by row: x changes fastest, and y changes after each complete row. The mesh/rows=4 setting tells PGFPlots that there are four rows in this grid.

If your source data is only a matrix of numbers, you must still supply or define the coordinate values. For a regularly spaced grid, these can be integer indices, as in the example. For a grid with unequal spacing, provide the actual x and y coordinates for each value rather than relying on the row and column numbers.

What the plotting options do

• view={0}{90} looks straight down onto the surface, so the z-values appear as a two-dimensional color field.
• surf treats the data as a surface, and shader=interp interpolates the color between sample points.
• point meta=z explicitly uses the z-value to choose the color. point meta min and point meta max fix the color scale, making plots easier to compare.
• colorbar displays that scale, and colormap/viridis selects the color map.
• contour gnuplot={levels={1,2,3},labels=false} requests contour lines at z-values 1, 2, and 3, without labels. The second plot uses the same data grid so the contours align with the color map.

The two tables are repeated to keep the example self-contained. In a larger project, store the grid in a data file and read it for both plots with table {data.dat} or the appropriate PGFPlots table syntax for your file format.

Common mistakes

Wrong mesh/rows value. It should match the number of grid rows, not the number of points in the whole table. For a grid with 20 points arranged as 4 rows of 5, use mesh/rows=4.

Inconsistent point order. Each row must contain the same number of points, and the coordinates must follow a consistent order. Scrambled points can create crossed or misplaced surface cells and incorrect contours.

Missing coordinates. A list of z-values alone does not identify the x-y locations unless you use a matrix-specific input method that defines those coordinates. Supplying explicit x, y, and z columns makes the grid structure clear.

Expecting contour plotting to be built in without external tools. contour gnuplot uses Gnuplot. If you cannot enable shell escape, you can still draw the top-view color map with the surf plot alone, or generate contour data externally and plot the resulting lines.

Comparing plots with automatic color limits. If each plot chooses its own color range, the same color may represent different values in different figures. Set point meta min and point meta max to a common range when comparisons matter.