{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# pcolormesh grids and shading\n\n`.axes.Axes.pcolormesh` and `~.axes.Axes.pcolor` have a few options for\nhow grids are laid out and the shading between the grid points.\n\nGenerally, if *Z* has shape *(M, N)* then the grid *X* and *Y* can be\nspecified with either shape *(M+1, N+1)* or *(M, N)*, depending on the\nargument for the ``shading`` keyword argument.  Note that below we specify\nvectors *x* as either length N or N+1 and *y* as length M or M+1, and\n`~.axes.Axes.pcolormesh` internally makes the mesh matrices *X* and *Y* from\nthe input vectors.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\nimport numpy as np"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Flat Shading\n\nThe grid specification with the least assumptions is ``shading='flat'``\nand if the grid is one larger than the data in each dimension, i.e. has shape\n*(M+1, N+1)*.  In that case *X* and *Y* specify the corners of quadrilaterals\nthat are colored with the values in *Z*. Here we specify the edges of the\n*(3, 5)* quadrilaterals with *X* and *Y* that are *(4, 6)*.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "nrows = 3\nncols = 5\nZ = np.arange(nrows * ncols).reshape(nrows, ncols)\nx = np.arange(ncols + 1)\ny = np.arange(nrows + 1)\n\nfig, ax = plt.subplots()\nax.pcolormesh(x, y, Z, shading='flat', vmin=Z.min(), vmax=Z.max())\n\n\ndef _annotate(ax, x, y, title):\n    # this all gets repeated below:\n    X, Y = np.meshgrid(x, y)\n    ax.plot(X.flat, Y.flat, 'o', color='m')\n    ax.set_xlim(-0.7, 5.2)\n    ax.set_ylim(-0.7, 3.2)\n    ax.set_title(title)\n\n_annotate(ax, x, y, \"shading='flat'\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Flat Shading, same shape grid\n\nOften, however, data is provided where *X* and *Y* match the shape of *Z*.\nWhile this makes sense for other ``shading`` types, it is not permitted\nwhen ``shading='flat'``. Historically, Matplotlib silently dropped the last\nrow and column of *Z* in this case, to match Matlab's behavior. If this\nbehavior is still desired, simply drop the last row and column manually:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "x = np.arange(ncols)  # note *not* ncols + 1 as before\ny = np.arange(nrows)\nfig, ax = plt.subplots()\nax.pcolormesh(x, y, Z[:-1, :-1], shading='flat', vmin=Z.min(), vmax=Z.max())\n_annotate(ax, x, y, \"shading='flat': X, Y, C same shape\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Nearest Shading, same shape grid\n\nUsually, dropping a row and column of data is not what the user means when\nthey make *X*, *Y* and *Z* all the same shape.  For this case, Matplotlib\nallows ``shading='nearest'`` and centers the colored quadrilaterals on the\ngrid points.\n\nIf a grid that is not the correct shape is passed with ``shading='nearest'``\nan error is raised.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig, ax = plt.subplots()\nax.pcolormesh(x, y, Z, shading='nearest', vmin=Z.min(), vmax=Z.max())\n_annotate(ax, x, y, \"shading='nearest'\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Auto Shading\n\nIt's possible that the user would like the code to automatically choose which\nto use, in this case ``shading='auto'`` will decide whether to use 'flat' or\n'nearest' shading based on the shapes of *X*, *Y* and *Z*.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig, axs = plt.subplots(2, 1, layout='constrained')\nax = axs[0]\nx = np.arange(ncols)\ny = np.arange(nrows)\nax.pcolormesh(x, y, Z, shading='auto', vmin=Z.min(), vmax=Z.max())\n_annotate(ax, x, y, \"shading='auto'; X, Y, Z: same shape (nearest)\")\n\nax = axs[1]\nx = np.arange(ncols + 1)\ny = np.arange(nrows + 1)\nax.pcolormesh(x, y, Z, shading='auto', vmin=Z.min(), vmax=Z.max())\n_annotate(ax, x, y, \"shading='auto'; X, Y one larger than Z (flat)\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Gouraud Shading\n\n[Gouraud shading](https://en.wikipedia.org/wiki/Gouraud_shading) can also\nbe specified, where the color in the quadrilaterals is linearly interpolated\nbetween the grid points.  The shapes of *X*, *Y*, *Z* must be the same.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig, ax = plt.subplots(layout='constrained')\nx = np.arange(ncols)\ny = np.arange(nrows)\nax.pcolormesh(x, y, Z, shading='gouraud', vmin=Z.min(), vmax=Z.max())\n_annotate(ax, x, y, \"shading='gouraud'; X, Y same shape as Z\")\n\nplt.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. admonition:: References\n\n   The use of the following functions, methods, classes and modules is shown\n   in this example:\n\n   - `matplotlib.axes.Axes.pcolormesh` / `matplotlib.pyplot.pcolormesh`\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.13.5"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}