<divid="unreleased-message"> You are reading an old version of the documentation (v3.2.2). For the latest version see <ahref="https://matplotlib.org/stable/api/cm_api.html">https://matplotlib.org/stable/api/cm_api.html</a></div>
<spanid="matplotlib-cm"></span><h1><codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.cm</span></code><aclass="headerlink" href="#module-matplotlib.cm" title="Permalink to this headline">¶</a></h1>
<p>Builtin colormaps, colormap handling utilities, and the <aclass="reference internal" href="#matplotlib.cm.ScalarMappable" title="matplotlib.cm.ScalarMappable"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">ScalarMappable</span></code></a> mixin.</p>
<divclass="admonition seealso">
<pclass="first admonition-title">See also</p>
<p><aclass="reference internal" href="../gallery/color/colormap_reference.html"><spanclass="doc">Colormap reference</span></a> for a list of builtin colormaps.</p>
<p><aclass="reference internal" href="../tutorials/colors/colormap-manipulation.html"><spanclass="doc">Creating Colormaps in Matplotlib</span></a> for examples of how to
make colormaps.</p>
<p><aclass="reference internal" href="../tutorials/colors/colormaps.html"><spanclass="doc">Choosing Colormaps in Matplotlib</span></a> an in-depth discussion of
choosing colormaps.</p>
<pclass="last"><aclass="reference internal" href="../tutorials/colors/colormapnorms.html"><spanclass="doc">Colormap Normalization</span></a> for more details about data
normalization.</p>
</div>
<dlclass="py class">
<dtid="matplotlib.cm.ScalarMappable">
<emclass="property">class </em><codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">ScalarMappable</code><spanclass="sig-paren">(</span><em><spanclass="n">norm</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">cmap</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable" title="Permalink to this definition">¶</a></dt>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>norm</strong><spanclass="classifier"><aclass="reference internal" href="_as_gen/matplotlib.colors.Normalize.html#matplotlib.colors.Normalize" title="matplotlib.colors.Normalize"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.colors.Normalize</span></code></a> instance</span></dt><dd><p>The normalizing object which scales data, typically into the
If <em>None</em>, <em>norm</em> defaults to a <em>colors.Normalize</em> object which
initializes its scaling based on the first data processed.</p>
</dd>
<dt><strong>cmap</strong><spanclass="classifier">str or <aclass="reference internal" href="_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap" title="matplotlib.colors.Colormap"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Colormap</span></code></a> instance</span></dt><dd><p>The colormap used to map normalized data values to RGBA colors.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.add_checker">
<codeclass="descname">add_checker</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">checker</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.add_checker"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.add_checker" title="Permalink to this definition">¶</a></dt>
<dd><p>Add an entry to a dictionary of boolean flags
that are set to True when the mappable is changed.</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.autoscale">
<codeclass="descname">autoscale</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.autoscale"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.autoscale" title="Permalink to this definition">¶</a></dt>
<dd><p>Autoscale the scalar limits on the norm instance using the
<codeclass="descname">autoscale_None</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.autoscale_None"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.autoscale_None" title="Permalink to this definition">¶</a></dt>
<dd><p>Autoscale the scalar limits on the norm instance using the
current array, changing only limits that are None</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.changed">
<codeclass="descname">changed</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.changed"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.changed" title="Permalink to this definition">¶</a></dt>
<dd><p>Call this whenever the mappable is changed to notify all the
<codeclass="descname">check_update</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">checker</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.check_update"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.check_update" title="Permalink to this definition">¶</a></dt>
<dd><p>If mappable has changed since the last check,
return True; else return False</p>
</dd></dl>
<dlclass="py attribute">
<dtid="matplotlib.cm.ScalarMappable.cmap">
<codeclass="descname">cmap</code><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.cmap" title="Permalink to this definition">¶</a></dt>
<dd><p>The Colormap instance of this ScalarMappable.</p>
</dd></dl>
<dlclass="py attribute">
<dtid="matplotlib.cm.ScalarMappable.colorbar">
<codeclass="descname">colorbar</code><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.colorbar" title="Permalink to this definition">¶</a></dt>
<dd><p>The last colorbar associated with this ScalarMappable. May be None.</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.get_alpha">
<codeclass="descname">get_alpha</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.get_alpha"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.get_alpha" title="Permalink to this definition">¶</a></dt>
<codeclass="descname">get_array</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.get_array"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.get_array" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the array</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.get_clim">
<codeclass="descname">get_clim</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.get_clim"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.get_clim" title="Permalink to this definition">¶</a></dt>
<dd><p>return the min, max of the color limits for image scaling</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.get_cmap">
<codeclass="descname">get_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.get_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.get_cmap" title="Permalink to this definition">¶</a></dt>
<dd><p>return the colormap</p>
</dd></dl>
<dlclass="py attribute">
<dtid="matplotlib.cm.ScalarMappable.norm">
<codeclass="descname">norm</code><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.norm" title="Permalink to this definition">¶</a></dt>
<dd><p>The Normalization instance of this ScalarMappable.</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.set_array">
<codeclass="descname">set_array</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">A</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.set_array"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.set_array" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the image array from numpy array <em>A</em>.</p>
<codeclass="descname">set_clim</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">vmin</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">vmax</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.set_clim"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.set_clim" title="Permalink to this definition">¶</a></dt>
<p>The limits may also be passed as a tuple (<em>vmin</em>, <em>vmax</em>) as a
single positional argument.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.set_cmap">
<codeclass="descname">set_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">cmap</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.set_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.set_cmap" title="Permalink to this definition">¶</a></dt>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>cmap</strong><spanclass="classifier">colormap or registered colormap name</span></dt><dd></dd>
</dl>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.set_norm">
<codeclass="descname">set_norm</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">norm</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.set_norm"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.set_norm" title="Permalink to this definition">¶</a></dt>
<p>If there are any colorbars using the mappable for this norm, setting
the norm of the mappable will reset the norm, locator, and formatters
on the colorbar to default.</p>
</dd></dl>
<dlclass="py method">
<dtid="matplotlib.cm.ScalarMappable.to_rgba">
<codeclass="descname">to_rgba</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">x</span></em>, <em><spanclass="n">alpha</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">bytes</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <em><spanclass="n">norm</span><spanclass="o">=</span><spanclass="default_value">True</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#ScalarMappable.to_rgba"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.ScalarMappable.to_rgba" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a normalized rgba array corresponding to <em>x</em>.</p>
<p>In the normal case, <em>x</em> is a 1-D or 2-D sequence of scalars, and
the corresponding ndarray of rgba values will be returned,
based on the norm and colormap set for this ScalarMappable.</p>
<p>There is one special case, for handling images that are already
rgb or rgba, such as might have been read from an image file.
If <em>x</em> is an ndarray with 3 dimensions,
and the last dimension is either 3 or 4, then it will be
treated as an rgb or rgba array, and no mapping will be done.
The array can be uint8, or it can be floating point with
values in the 0-1 range; otherwise a ValueError will be raised.
If it is a masked array, the mask will be ignored.
If the last dimension is 3, the <em>alpha</em> kwarg (defaulting to 1)
will be used to fill in the transparency. If the last dimension
is 4, the <em>alpha</em> kwarg is ignored; it does not
replace the pre-existing alpha. A ValueError will be raised
if the third dimension is other than 3 or 4.</p>
<p>In either case, if <em>bytes</em> is <em>False</em> (default), the rgba
array will be floats in the 0-1 range; if it is <em>True</em>,
the returned rgba array will be uint8 in the 0 to 255 range.</p>
<p>If norm is False, no normalization of the input data is
performed, and it is assumed to be in the range (0-1).</p>
</dd></dl>
</dd></dl>
<dlclass="py function">
<dtid="matplotlib.cm.get_cmap">
<codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">get_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">name</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">lut</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#get_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.get_cmap" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a colormap instance, defaulting to rc values if <em>name</em> is None.</p>
<p>Colormaps added with <aclass="reference internal" href="#matplotlib.cm.register_cmap" title="matplotlib.cm.register_cmap"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">register_cmap()</span></code></a> take precedence over
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>name</strong><spanclass="classifier"><aclass="reference internal" href="_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap" title="matplotlib.colors.Colormap"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.colors.Colormap</span></code></a> or str or None, default: None</span></dt><dd><p>If a <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Colormap</span></code> instance, it will be returned. Otherwise, the name of
a colormap known to Matplotlib, which will be resampled by <em>lut</em>. The
default, None, means <codeclass="docutils literal notranslate"><aclass="reference external" href="../tutorials/introductory/customizing.html?highlight=image.cmap#a-sample-matplotlibrc-file"><spanclass="pre">rcParams["image.cmap"]</span></a></code> (default: 'viridis').</p>
</dd>
<dt><strong>lut</strong><spanclass="classifier">int or None, default: None</span></dt><dd><p>If <em>name</em> is not already a Colormap instance and <em>lut</em> is not None, the
colormap will be resampled to have <em>lut</em> entries in the lookup table.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="py function">
<dtid="matplotlib.cm.register_cmap">
<codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">register_cmap</code><spanclass="sig-paren">(</span><em><spanclass="n">name</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">cmap</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">data</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">lut</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#register_cmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.register_cmap" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a colormap to the set recognized by <aclass="reference internal" href="#matplotlib.cm.get_cmap" title="matplotlib.cm.get_cmap"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">get_cmap()</span></code></a>.</p>
<p>In the first case, <em>cmap</em> must be a <aclass="reference internal" href="_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap" title="matplotlib.colors.Colormap"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.colors.Colormap</span></code></a>
instance. The <em>name</em> is optional; if absent, the name will
be the <codeclass="xref py py-attr docutils literal notranslate"><spanclass="pre">name</span></code> attribute of the <em>cmap</em>.</p>
<p>In the second case, the three arguments are passed to
<codeclass="descclassname">matplotlib.cm.</code><codeclass="descname">revcmap</code><spanclass="sig-paren">(</span><em><spanclass="n">data</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/cm.html#revcmap"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.cm.revcmap" title="Permalink to this definition">¶</a></dt>
<dd><p>[<em>Deprecated</em>] Can only handle specification <em>data</em> in dictionary format.</p>
<pclass="rubric">Notes</p>
<divclass="deprecated">
<p><spanclass="versionmodified deprecated">Deprecated since version 3.2.</span></p>